docs: let go of *

Since we are no longer using sgml mode, using /* */ to
escape block comments inside examples does not work anymore.
Switch to using line comments with //

gio/gappinfo.c

@@ -71,7 +71,7 @@
  *
  * if (g_file_has_uri_scheme (file, "cdda"))
  *   {
- *     /* do something special with uri */
+ *     // do something special with uri
  *   }
  * g_object_unref (file);
  * ]|

gio/gapplicationcommandline.c

@@ -165,10 +165,10 @@
  * {
  *   GApplicationCommandLine *cmdline = data;
  *
- *   /* do the heavy lifting in an idle */
+ *   // do the heavy lifting in an idle
  *
  *   g_application_command_line_set_exit_status (cmdline, 0);
- *   g_object_unref (cmdline); /* this releases the application */
+ *   g_object_unref (cmdline); // this releases the application
  *
  *   return G_SOURCE_REMOVE;
  * }
@@ -177,7 +177,7 @@
  * command_line (GApplication            *application,
  *               GApplicationCommandLine *cmdline)
  * {
- *   /* keep the application running until we are done with this commandline */
+ *   // keep the application running until we are done with this commandline
  *   g_application_hold (application);
  *
  *   g_object_set_data_full (G_OBJECT (cmdline),

gio/gcancellable.c

@@ -106,13 +106,12 @@ g_cancellable_class_init (GCancellableClass *klass)
    *
    * An example of how to us this:
    * |[<!-- language="C" -->
-   *     /&ast; Make sure we don't do unnecessary work if already cancelled &ast;/
+   *     // Make sure we don't do unnecessary work if already cancelled
    *     if (g_cancellable_set_error_if_cancelled (cancellable, error))
    *       return;
    *
-   *     /&ast; Set up all the data needed to be able to
-   *      &ast; handle cancellation of the operation
-   *      &ast;/
+   *     // Set up all the data needed to be able to handle cancellation
+   *     // of the operation
    *     my_data = my_data_new (...);
    *
    *     id = 0;
@@ -121,13 +120,12 @@ g_cancellable_class_init (GCancellableClass *klass)
    *     			      G_CALLBACK (cancelled_handler)
    *     			      data, NULL);
    *
-   *     /&ast; cancellable operation here... &ast;/
+   *     // cancellable operation here...
    *
    *     g_cancellable_disconnect (cancellable, id);
    *
-   *     /&ast; cancelled_handler is never called after this,
-   *      &ast; it is now safe to free the data
-   *      &ast;/
+   *     // cancelled_handler is never called after this, it is now safe
+   *     // to free the data
    *     my_data_free (my_data);  
    * ]|
    *

gio/gdbuserror.c

@@ -56,7 +56,7 @@
  * is typically done in the function returning the #GQuark for the
  * error domain:
  * |[<!-- language="C" -->
- * /&ast; foo-bar-error.h: &ast;/
+ * // foo-bar-error.h:
  *
  * #define FOO_BAR_ERROR (foo_bar_error_quark ())
  * GQuark foo_bar_error_quark (void);
@@ -66,10 +66,10 @@
  *   FOO_BAR_ERROR_FAILED,
  *   FOO_BAR_ERROR_ANOTHER_ERROR,
  *   FOO_BAR_ERROR_SOME_THIRD_ERROR,
- *   FOO_BAR_N_ERRORS /&ast;< skip >&ast;/
+ *   FOO_BAR_N_ERRORS / *< skip >* /
  * } FooBarError;
  *
- * /&ast; foo-bar-error.c: &ast;/
+ * // foo-bar-error.c:
  *
  * static const GDBusErrorEntry foo_bar_error_entries[] =
  * {
@@ -78,7 +78,7 @@
  *   {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
  * };
  *
- * /&ast; Ensure that every error code has an associated D-Bus error name &ast;/
+ * // Ensure that every error code has an associated D-Bus error name
  * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
  *
  * GQuark

gio/giomodule.c

@@ -80,13 +80,13 @@
  *  |[<!-- language="C" -->
  *  GIOExtensionPoint *ep;
  *
- *  /&ast; Register an extension point &ast;/
+ *  // Register an extension point
  *  ep = g_io_extension_point_register ("my-extension-point");
  *  g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
  *  ]|
  *
  *  |[<!-- language="C" -->
- *  /&ast; Implement an extension point &ast;/
+ *  // Implement an extension point
  *  G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
  *  g_io_extension_point_implement ("my-extension-point",
  *                                  my_example_impl_get_type (),

gio/gmemoryoutputstream.c

@@ -368,13 +368,13 @@ g_memory_output_stream_init (GMemoryOutputStream *stream)
  * allocation for itself).
  *
  * |[<!-- language="C" -->
- * /&ast; a stream that can grow &ast;/
+ * // a stream that can grow
  * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
  *
- * /&ast; another stream that can grow &ast;/
+ * // another stream that can grow
  * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
  *
- * /&ast; a fixed-size stream &ast;/
+ * // a fixed-size stream
  * data = malloc (200);
  * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
  * ]|

gio/gsimpleaction.c

@@ -409,7 +409,7 @@ g_simple_action_class_init (GSimpleActionClass *class)
    *
    *   requested = g_variant_get_int32 (value);
    *
-   *   /* Volume only goes from 0 to 10 */
+   *   // Volume only goes from 0 to 10
    *   if (0 <= requested && requested <= 10)
    *     g_simple_action_set_state (action, value);
    * }

gio/gsimpleasyncresult.c

@@ -111,9 +111,8 @@
  * baked_cb (Cake    *cake,
  *           gpointer user_data)
  * {
- *   /* In this example, this callback is not given a reference to the cake, so
- *    * the GSimpleAsyncResult has to take a reference to it.
- *    */
+ *   // In this example, this callback is not given a reference to the cake,
+ *   // so the GSimpleAsyncResult has to take a reference to it.
  *   GSimpleAsyncResult *result = user_data;
  *
  *   if (cake == NULL)
@@ -127,12 +126,11 @@
  *                                                g_object_unref);
  *
  *
- *   /* In this example, we assume that baked_cb is called as a callback from
- *    * the mainloop, so it's safe to complete the operation synchronously here.
- *    * If, however, _baker_prepare_cake () might call its callback without
- *    * first returning to the mainloop — inadvisable, but some APIs do so —
- *    * we would need to use g_simple_async_result_complete_in_idle().
- *    */
+ *   // In this example, we assume that baked_cb is called as a callback from
+ *   // the mainloop, so it's safe to complete the operation synchronously here.
+ *   // If, however, _baker_prepare_cake () might call its callback without
+ *   // first returning to the mainloop — inadvisable, but some APIs do so —
+ *   // we would need to use g_simple_async_result_complete_in_idle().
  *   g_simple_async_result_complete (result);
  *   g_object_unref (result);
  * }
@@ -171,9 +169,8 @@
  *                                                  g_object_unref);
  *       g_simple_async_result_complete_in_idle (simple);
  *       g_object_unref (simple);
- *       /* Drop the reference returned by _baker_get_cached_cake(); the
- *        * GSimpleAsyncResult has taken its own reference.
- *        */
+ *       // Drop the reference returned by _baker_get_cached_cake();
+ *       // the GSimpleAsyncResult has taken its own reference.
  *       g_object_unref (cake);
  *       return;
  *     }

gio/gsocketconnectable.c

@@ -49,10 +49,9 @@
  *   enumerator = g_socket_connectable_enumerate (addr);
  *   g_object_unref (addr);
  *
- *   /* Try each sockaddr until we succeed. Record the first
- *    * connection error, but not any further ones (since they'll probably
- *    * be basically the same as the first).
- *    */
+ *   // Try each sockaddr until we succeed. Record the first connection error,
+ *   // but not any further ones (since they'll probably be basically the same
+ *   // as the first).
  *   while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
  *     {
  *       conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
@@ -64,18 +63,15 @@
  *     {
  *       if (conn_error)
  *         {
- *           /* We couldn't connect to the first address, but we succeeded
- *            * in connecting to a later address.
- *            */
+ *           // We couldn't connect to the first address, but we succeeded
+ *           // in connecting to a later address.
  *           g_error_free (conn_error);
  *         }
  *       return conn;
  *     }
  *   else if (error)
  *     {
- *       /* Either the initial lookup failed, or else the caller
- *        * cancelled us.
- *        */
+ *       /// Either initial lookup failed, or else the caller cancelled us.
  *       if (conn_error)
  *         g_error_free (conn_error);
  *       return NULL;

gio/gtask.c

@@ -82,7 +82,7 @@
  *       if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
  *         {
  *           g_object_unref (cake);
- *           /* g_task_return_error() takes ownership of error */
+ *           // g_task_return_error() takes ownership of error
  *           g_task_return_error (task, error);
  *           g_object_unref (task);
  *           return;
@@ -119,7 +119,7 @@
  *       cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
  *       if (cake != NULL)
  *         {
- *           /* _baker_get_cached_cake() returns a reffed cake */
+ *           // _baker_get_cached_cake() returns a reffed cake
  *           g_task_return_pointer (task, cake, g_object_unref);
  *           g_object_unref (task);
  *           return;
@@ -189,9 +189,8 @@
  *           return;
  *         }
  *
- *       /* baking_data_free() will drop its ref on the cake, so
- *        * we have to take another here to give to the caller.
- *        */
+ *       // baking_data_free() will drop its ref on the cake, so we have to
+ *       // take another here to give to the caller.
  *       g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
  *       g_object_unref (task);
  *     }
@@ -225,7 +224,7 @@
  *
  *       bd->cake = cake;
  *
- *       /* Bail out now if the user has already cancelled */
+ *       // Bail out now if the user has already cancelled
  *       if (g_task_return_error_if_cancelled (task))
  *         {
  *           g_object_unref (task);
@@ -239,9 +238,8 @@
  *           GSource *source;
  *
  *           source = cake_decorator_wait_source_new (cake);
- *           /* Attach @source to @task's GMainContext and have it call
- *            * decorator_ready() when it is ready.
- *            */
+ *           // Attach @source to @task's GMainContext and have it call
+ *           // decorator_ready() when it is ready.
  *           g_task_attach_source (task, source,
  *                                 G_CALLBACK (decorator_ready));
  *           g_source_unref (source);
@@ -397,22 +395,20 @@
  *           return;
  *         }
  *
- *       /* If the task has already been cancelled, then we don't
- *        * want to add the cake to the cake cache. Likewise, we don't
- *        * want to have the task get cancelled in the middle of
- *        * updating the cache. g_task_set_return_on_cancel() will
- *        * return %TRUE here if it managed to disable return-on-cancel,
- *        * or %FALSE if the task was cancelled before it could.
- *        */
+ *       // If the task has already been cancelled, then we don't want to add
+ *       // the cake to the cake cache. Likewise, we don't  want to have the
+ *       // task get cancelled in the middle of updating the cache.
+ *       // g_task_set_return_on_cancel() will return %TRUE here if it managed
+ *       // to disable return-on-cancel, or %FALSE if the task was cancelled
+ *       // before it could.
  *       if (g_task_set_return_on_cancel (task, FALSE))
  *         {
- *           /* If the caller cancels at this point, their
- *            * GAsyncReadyCallback won't be invoked until we return,
- *            * so we don't have to worry that this code will run at
- *            * the same time as that code does. But if there were
- *            * other functions that might look at the cake cache,
- *            * then we'd probably need a GMutex here as well.
- *            */
+ *           // If the caller cancels at this point, their
+ *           // GAsyncReadyCallback won't be invoked until we return,
+ *           // so we don't have to worry that this code will run at
+ *           // the same time as that code does. But if there were
+ *           // other functions that might look at the cake cache,
+ *           // then we'd probably need a GMutex here as well.
  *           baker_add_cake_to_cache (baker, cake);
  *           g_task_return_pointer (task, cake, g_object_unref);
  *         }
@@ -432,7 +428,8 @@
  *       GTask *task;
  *
  *       cake_data = g_slice_new (CakeData);
- *       /* ... */
+ *
+ *       ...
  *
  *       task = g_task_new (self, cancellable, callback, user_data);
  *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
@@ -454,7 +451,8 @@
  *       Cake *cake;
  *
  *       cake_data = g_slice_new (CakeData);
- *       /* ... */
+ *
+ *       ...
  *
  *       task = g_task_new (self, cancellable, NULL, NULL);
  *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);

gio/gvolume.c

@@ -626,9 +626,9 @@ g_volume_enumerate_identifiers (GVolume *volume)
  *   GFile *mount_root
  *   GFile *volume_activation_root;
  *
- *   mount = g_volume_get_mount (volume); /* mounted, so never NULL */
+ *   mount = g_volume_get_mount (volume); // mounted, so never NULL
  *   mount_root = g_mount_get_root (mount);
- *   volume_activation_root = g_volume_get_activation_root (volume); /* assume not NULL */
+ *   volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
  * ]|
  * then the expression
  * |[<!-- language="C" -->