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" -->

glib/garray.c

@@ -71,9 +71,8 @@
  * |[<!-- language="C" -->
  *   GArray *garray;
  *   gint i;
- *   /&ast; We create a new array to store gint values.
- *    &ast; We don't want it zero-terminated or cleared to 0's.
- *    &ast;/
+ *   // We create a new array to store gint values.
+ *   // We don't want it zero-terminated or cleared to 0's.
  *   garray = g_array_new (FALSE, FALSE, sizeof (gint));
  *   for (i = 0; i < 10000; i++)
  *     g_array_append_val (garray, i);
@@ -122,9 +121,8 @@ struct _GRealArray
  * This example gets a pointer to an element in a #GArray:
  * |[<!-- language="C" -->
  *   EDayViewEvent *event;
- *   /&ast; This gets a pointer to the 4th element
- *    &ast; in the array of EDayViewEvent structs.
- *    &ast;/
+ *   // This gets a pointer to the 4th element in the array of
+ *   // EDayViewEvent structs.
  *   event = &g_array_index (events, EDayViewEvent, 3);
  * ]|
  *

glib/gerror.c

@@ -69,14 +69,14 @@
  * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
  * if (err != NULL)
  *   {
- *     /* Report error to user, and free error */
+ *     // Report error to user, and free error
  *     g_assert (contents == NULL);
  *     fprintf (stderr, "Unable to read file: %s\n", err->message);
  *     g_error_free (err);
  *   }
  * else
  *   {
- *     /* Use file contents */
+ *     // Use file contents
  *     g_assert (contents != NULL);
  *   }
  * ]|
@@ -89,10 +89,12 @@
  * are only interested in whether it failed and don't need to display
  * an error message, you can pass %NULL for the @error argument:
  * |[<!-- language="C" -->
- * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /&ast; ignore errors &ast;/
- *   /&ast; no error occurred &ast;/ ;
+ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
+ *   // no error occurred 
+ *   ;
  * else
- *   /&ast; error &ast;/ ;
+ *   // error
+ *   ;
  * ]|
  *
  * The #GError object contains three fields: @domain indicates the module
@@ -125,9 +127,9 @@
  *   if (fd < 0)
  *     {
  *       g_set_error (error,
- *                    FOO_ERROR,                 /&ast; error domain &ast;/
- *                    FOO_ERROR_BLAH,            /&ast; error code &ast;/
- *                    "Failed to open file: %s", /&ast; error message format string &ast;/
+ *                    FOO_ERROR,                 // error domain
+ *                    FOO_ERROR_BLAH,            // error code
+ *                    "Failed to open file: %s", // error message format string
  *                    g_strerror (errno));
  *       return -1;
  *     }
@@ -148,12 +150,12 @@
  *
  *   if (!sub_function_that_can_fail (err))
  *     {
- *       /&ast; assert that error was set by the sub-function &ast;/
+ *       // assert that error was set by the sub-function
  *       g_assert (err == NULL || *err != NULL);
  *       return FALSE;
  *     }
  *
- *   /&ast; otherwise continue, no error occurred &ast;/
+ *   // otherwise continue, no error occurred
  *   g_assert (err == NULL || *err == NULL);
  * }
  * ]|
@@ -175,14 +177,13 @@
  *
  *   if (tmp_error != NULL)
  *     {
- *       /&ast; store tmp_error in err, if err != NULL,
- *        &ast; otherwise call g_error_free() on tmp_error
- *        &ast;/
+ *       // store tmp_error in err, if err != NULL,
+ *       // otherwise call g_error_free() on tmp_error
  *       g_propagate_error (err, tmp_error);
  *       return FALSE;
  *     }
  *
- *   /&ast; otherwise continue, no error occurred &ast;/
+ *   // otherwise continue, no error occurred
  * }
  * ]|
  *
@@ -222,7 +223,7 @@
  *
  *   g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
  *
- *   sub_function_that_can_fail (NULL); /&ast; ignore errors &ast;/
+ *   sub_function_that_can_fail (NULL); // ignore errors
  *
  *   tmp_error = NULL;
  *   other_function_that_can_fail (&tmp_error);

glib/gfileutils.c

@@ -290,11 +290,11 @@ g_mkdir_with_parents (const gchar *pathname,
  * to know whether it is safe to write to a file without being
  * tricked into writing into a different location. It doesn't work!
  * |[<!-- language="C" -->
- * /&ast; DON'T DO THIS &ast;/
+ *  // DON'T DO THIS
  *  if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) 
  *    {
  *      fd = g_open (filename, O_WRONLY);
- *      /&ast; write to fd &ast;/
+ *      // write to fd
  *    }
  * ]|
  *

glib/ghash.c

@@ -687,7 +687,7 @@ g_hash_table_new_full (GHashFunc      hash_func,
  * g_hash_table_iter_init (&iter, hash_table);
  * while (g_hash_table_iter_next (&iter, &key, &value))
  *   {
- *     /* do something with key and value */
+ *     // do something with key and value
  *   }
  * ]|
  *

glib/glist.c

@@ -77,7 +77,7 @@
  * GList *l;
  * for (l = list; l != NULL; l = l->next)
  *   {
- *     /* do something with l->data */
+ *     // do something with l->data
  *   }
  * ]|
  *
@@ -92,7 +92,7 @@
  *     GList *next = l->next;
  *     if (should_be_removed (l))
  *       {
- *         /* possibly free l->data */
+ *         // possibly free l->data
  *         list = g_list_delete_link (list, l);
  *       }
  *     l = next;
@@ -234,14 +234,14 @@ g_list_free_full (GList          *list,
  * the list with g_list_reverse() when all elements have been added.
  *
  * |[<!-- language="C" -->
- * /&ast; Notice that these are initialized to the empty list. &ast;/
+ * // Notice that these are initialized to the empty list.
  * GList *string_list = NULL, *number_list = NULL;
  *
- * /&ast; This is a list of strings. &ast;/
+ * // This is a list of strings.
  * string_list = g_list_append (string_list, "first");
  * string_list = g_list_append (string_list, "second");
  * 
- * /&ast; This is a list of integers. &ast;/
+ * // This is a list of integers.
  * number_list = g_list_append (number_list, GINT_TO_POINTER (27));
  * number_list = g_list_append (number_list, GINT_TO_POINTER (14));
  * ]|
@@ -286,7 +286,7 @@ g_list_append (GList    *list,
  * which will have changed, so make sure you store the new value. 
  *
  * |[<!-- language="C" -->
- * /&ast; Notice that it is initialized to the empty list. &ast;/
+ * // Notice that it is initialized to the empty list.
  * GList *list = NULL;
  *
  * list = g_list_prepend (list, "last");

glib/gmain.c

@@ -2879,7 +2879,7 @@ g_main_current_source (void)
  *   SomeWidget *self = data;
  *    
  *   GDK_THREADS_ENTER ();
- *   /* do stuff with self */
+ *   // do stuff with self
  *   self->idle_id = 0;
  *   GDK_THREADS_LEAVE ();
  *    
@@ -2919,7 +2919,7 @@ g_main_current_source (void)
  *   GDK_THREADS_ENTER ();
  *   if (!g_source_is_destroyed (g_main_current_source ()))
  *     {
- *       /* do stuff with self */
+ *       // do stuff with self
  *     }
  *   GDK_THREADS_LEAVE ();
  *   

glib/gmarkup.c

@@ -2069,7 +2069,7 @@ g_markup_parse_context_get_user_data (GMarkupParseContext *context)
  *   if (strcmp (element_name, "count-these") == 0)
  *     start_counting (context);
  *
- *   /* else, handle other tags... */
+ *   // else, handle other tags...
  * }
  *
  * static void end_element (context, element_name, ...)
@@ -2077,7 +2077,7 @@ g_markup_parse_context_get_user_data (GMarkupParseContext *context)
  *   if (strcmp (element_name, "count-these") == 0)
  *     g_print ("Counted %d tags\n", end_counting (context));
  *
- *   /* else, handle other tags... */
+ *   // else, handle other tags...
  * }
  * ]|
  *

glib/gmessages.c

@@ -1146,9 +1146,8 @@ g_assert_warning (const char *log_domain,
  * For example:
  *
  * |[<!-- language="C" --> 
- *   /&ast; g_main_context_push_thread_default() should fail if the
- *    &ast; context is already owned by another thread.
- *    &ast;/
+ *   // g_main_context_push_thread_default() should fail if the
+ *   // context is already owned by another thread.
  *   g_test_expect_message (G_LOG_DOMAIN,
  *                          G_LOG_LEVEL_CRITICAL,
  *                          "assertion*acquired_context*failed");

glib/goption.c

@@ -120,7 +120,7 @@
  *       exit (1);
  *     }
  *
- *   /* ... */
+ *   ...
  *
  * }
  * ]|
@@ -161,18 +161,18 @@
  *   args = g_strdupv (argv);
  * #endif
  *
- *   /* ... setup context ... */
+ *   // set up context
  *
  *   if (!g_option_context_parse_strv (context, &args, &error))
  *     {
- *       /* ... error ... */
+ *       // error happened
  *     }
  *
- *   /* ... */
+ *   ...
  *
  *   g_strfreev (args);
  *
- *   /* ... */
+ *   ...
  * }
  * ]|
  */

glib/gregex.c

@@ -1643,7 +1643,7 @@ g_regex_match_simple (const gchar        *pattern,
  * static void
  * print_uppercase_words (const gchar *string)
  * {
- *   /* Print all uppercase-only words. */
+ *   // Print all uppercase-only words.
  *   GRegex *regex;
  *   GMatchInfo *match_info;
  *  
@@ -1716,7 +1716,7 @@ g_regex_match (const GRegex      *regex,
  * static void
  * print_uppercase_words (const gchar *string)
  * {
- *   /* Print all uppercase-only words. */
+ *   // Print all uppercase-only words.
  *   GRegex *regex;
  *   GMatchInfo *match_info;
  *   GError *error = NULL;
@@ -2853,7 +2853,7 @@ g_regex_replace_literal (const GRegex      *regex,
  *    return FALSE;
  * }
  *
- * /* ... */
+ * ...
  *
  * GRegex *reg;
  * GHashTable *h;
@@ -2870,7 +2870,7 @@ g_regex_replace_literal (const GRegex      *regex,
  * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
  * g_hash_table_destroy (h);
  *
- * /* ... */
+ * ...
  * ]|
  *
  * Returns: a newly allocated string containing the replacements

glib/gslice.c

@@ -96,17 +96,17 @@
  * gchar *mem[10000];
  * gint i;
  *
- * /* Allocate 10000 blocks. */
+ * // Allocate 10000 blocks.
  * for (i = 0; i < 10000; i++)
  *   {
  *     mem[i] = g_slice_alloc (50);
  *
- *     /&ast; Fill in the memory with some junk. &ast;/
+ *     // Fill in the memory with some junk.
  *     for (j = 0; j < 50; j++)
  *       mem[i][j] = i * j;
  *   }
  *
- * /&ast; Now free all of the blocks. &ast;/
+ * // Now free all of the blocks.
  * for (i = 0; i < 10000; i++)
  *   g_slice_free1 (50, mem[i]);
  * ]|
@@ -116,10 +116,10 @@
  * |[<!-- language="C" --> 
  * GRealArray *array;
  *
- * /&ast; Allocate one block, using the g_slice_new() macro. &ast;/
+ * // Allocate one block, using the g_slice_new() macro.
  * array = g_slice_new (GRealArray);
 
- * /&ast; We can now use array just like a normal pointer to a structure. &ast;/
+ * // We can now use array just like a normal pointer to a structure.
  * array->data            = NULL;
  * array->len             = 0;
  * array->alloc           = 0;
@@ -127,7 +127,7 @@
  * array->clear           = (clear ? 1 : 0);
  * array->elt_size        = elt_size;
  *
- * /&ast; We can free the block, so it can be reused. &ast;/
+ * // We can free the block, so it can be reused.
  * g_slice_free (GRealArray, array);
  * ]|
  */

glib/gslist.c

@@ -189,14 +189,14 @@ g_slist_free_full (GSList         *list,
  * the elements and reverse the list when all elements have been added.
  *
  * |[<!-- language="C" --> 
- * /&ast; Notice that these are initialized to the empty list. &ast;/
+ * // Notice that these are initialized to the empty list.
  * GSList *list = NULL, *number_list = NULL;
  *
- * /&ast; This is a list of strings. &ast;/
+ * // This is a list of strings.
  * list = g_slist_append (list, "first");
  * list = g_slist_append (list, "second");
  *
- * /&ast; This is a list of integers. &ast;/
+ * // This is a list of integers.
  * number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
  * number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
  * ]|
@@ -237,7 +237,7 @@ g_slist_append (GSList   *list,
  * may have changed, so make sure you store the new value.
  *
  * |[<!-- language="C" --> 
- * /&ast; Notice that it is initialized to the empty list. &ast;/
+ * // Notice that it is initialized to the empty list.
  * GSList *list = NULL;
  * list = g_slist_prepend (list, "last");
  * list = g_slist_prepend (list, "first");

glib/gtestutils.c

@@ -2644,7 +2644,7 @@ wait_for_child (GPid pid,
  *       {
  *         g_print ("some stdout text: somagic17\n");
  *         g_printerr ("some stderr text: semagic43\n");
- *         exit (0); /* successful test run */
+ *         exit (0); // successful test run
  *       }
  *     g_test_trap_assert_passed ();
  *     g_test_trap_assert_stdout ("*somagic17*");
@@ -2761,7 +2761,7 @@ g_test_trap_fork (guint64        usec_timeout,
  *         return;
  *       }
  *
- *     /* Reruns this same test in a subprocess */
+ *     // Reruns this same test in a subprocess
  *     g_test_trap_subprocess (NULL, 0, 0);
  *     g_test_trap_assert_failed ();
  *     g_test_trap_assert_stderr ("*ERROR*too large*");

glib/gthread-posix.c

@@ -820,12 +820,12 @@ g_cond_broadcast (GCond *cond)
  *   while (!current_data)
  *     if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
  *       {
- *         /* timeout has passed. */
+ *         // timeout has passed.
  *         g_mutex_unlock (&data_mutex);
  *         return NULL;
  *       }
  *
- *   /* there is data for us */
+ *   // there is data for us
  *   data = current_data;
  *   current_data = NULL;
  *
@@ -920,7 +920,7 @@ g_cond_wait_until (GCond  *cond,
  * |[<!-- language="C" --> 
  * static GPrivate name_key = G_PRIVATE_INIT (g_free);
  *
- * /&ast; return value should not be freed &ast;/
+ * // return value should not be freed
  * const gchar *
  * get_local_name (void)
  * {
@@ -934,7 +934,7 @@ g_cond_wait_until (GCond  *cond,
  * }
  *
  *
- * static GPrivate count_key;   /&ast; no free function &ast;/
+ * static GPrivate count_key;   // no free function
  *
  * gint
  * get_local_count (void)

glib/gthread.c

@@ -106,31 +106,31 @@
  *   there are thread-safe variants with a _r suffix, or you can
  *   look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
  *
- * - setenv() and unsetenv() manipulate the process environment in
- *   a not thread-safe way, and may interfere with getenv() calls
- *   in other threads. Note that getenv() calls may be hidden behind
+ * - The functions setenv() and unsetenv() manipulate the process
+ *   environment in a not thread-safe way, and may interfere with getenv()
+ *   calls in other threads. Note that getenv() calls may be hidden behind
  *   other APIs. For example, GNU gettext() calls getenv() under the
  *   covers. In general, it is best to treat the environment as readonly.
  *   If you absolutely have to modify the environment, do it early in
  *   main(), when no other threads are around yet.
  *
- * - setlocale() changes the locale for the entire process, affecting
- *   all threads. Temporary changes to the locale are often made to
- *   change the behavior of string scanning or formatting functions
+ * - The setlocale() function changes the locale for the entire process,
+ *   affecting all threads. Temporary changes to the locale are often made
+ *   to change the behavior of string scanning or formatting functions
  *   like scanf() or printf(). GLib offers a number of string APIs
  *   (like g_ascii_formatd() or g_ascii_strtod()) that can often be
  *   used as an alternative. Or you can use the uselocale() function
  *   to change the locale only for the current thread.
  *
- * - fork() only takes the calling thread into the child's copy of the
- *   process image. If other threads were executing in critical
+ * - The fork() function only takes the calling thread into the child's
+ *   copy of the process image. If other threads were executing in critical
  *   sections they could have left mutexes locked which could easily
  *   cause deadlocks in the new child. For this reason, you should
  *   call exit() or exec() as soon as possible in the child and only
  *   make signal-safe library calls before that.
  *
- * - daemon() uses fork() in a way contrary to what is described
- *   above. It should not be used with GLib programs.
+ * - The daemon() function uses fork() in a way contrary to what is
+ *   described above. It should not be used with GLib programs.
  *
  * GLib itself is internally completely thread-safe (all global data is
  * automatically locked), but individual data structure instances are
@@ -233,9 +233,8 @@
  *   {
  *     static int current_number = 0;
  *
- *     /* now do a very complicated calculation to calculate the new
- *      * number, this might for example be a random number generator
- *      */
+ *     // now do a very complicated calculation to calculate the new
+ *     // number, this might for example be a random number generator
  *     current_number = calc_next_number (current_number);
  *
  *     return current_number;
@@ -619,12 +618,12 @@ g_once_impl (GOnce       *once,
  *
  *   if (g_once_init_enter (&initialization_value))
  *     {
- *       gsize setup_value = 42; /* initialization code here */
+ *       gsize setup_value = 42; // initialization code here
  *
  *       g_once_init_leave (&initialization_value, setup_value);
  *     }
  *
- *   /* use initialization_value here */
+ *   // use initialization_value here
  * ]|
  *
  * Returns: %TRUE if the initialization section should be entered,

glib/gvariant.c

@@ -3032,7 +3032,7 @@ g_variant_iter_free (GVariantIter *iter)
  *
  * Here is an example for iterating with g_variant_iter_next_value():
  * |[<!-- language="C" --> 
- *   /&ast; recursively iterate a container &ast;/
+ *   // recursively iterate a container
  *   void
  *   iterate_container_recursive (GVariant *container)
  *   {
@@ -5469,7 +5469,7 @@ g_variant_get_child (GVariant    *value,
  *
  * Here is an example for memory management with g_variant_iter_next():
  * |[<!-- language="C" --> 
- *   /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
+ *   // Iterates a dictionary of type 'a{sv}'
  *   void
  *   iterate_dictionary (GVariant *dictionary)
  *   {
@@ -5483,7 +5483,7 @@ g_variant_get_child (GVariant    *value,
  *         g_print ("Item '%s' has type '%s'\n", key,
  *                  g_variant_get_type_string (value));
  *
- *         /&ast; must free data for ourselves &ast;/
+ *         // must free data for ourselves
  *         g_variant_unref (value);
  *         g_free (key);
  *       }
@@ -5561,7 +5561,7 @@ g_variant_iter_next (GVariantIter *iter,
  *
  * Here is an example for memory management with g_variant_iter_loop():
  * |[<!-- language="C" --> 
- *   /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
+ *   // Iterates a dictionary of type 'a{sv}'
  *   void
  *   iterate_dictionary (GVariant *dictionary)
  *   {
@@ -5575,9 +5575,8 @@ g_variant_iter_next (GVariantIter *iter,
  *         g_print ("Item '%s' has type '%s'\n", key,
  *                  g_variant_get_type_string (value));
  *
- *         /&ast; no need to free 'key' and 'value' here
- *          &ast; unless breaking out of this loop
- *          &ast;/
+ *         // no need to free 'key' and 'value' here
+ *         // unless breaking out of this loop
  *       }
  *   }
  * ]|

gmodule/gmodule.c

@@ -80,7 +80,7 @@
  *
  * Example: Calling a function defined in a GModule
  * |[<!-- language="C" --> 
- * /&ast; the function signature for 'say_hello' &ast;/
+ * // the function signature for 'say_hello'
  * typedef void (* SayHelloFunc) (const char *message);
  *
  * gboolean
@@ -115,7 +115,7 @@
  *       return FALSE;
  *     }
  *
- *   /&ast; call our function in the module &ast;/
+ *   // call our function in the module
  *   say_hello ("Hello world!");
  *
  *   if (!g_module_close (module))

gobject/gclosure.c

@@ -155,7 +155,7 @@ enum {
  * struct _MyClosure
  * {
  *   GClosure closure;
- *   /* extra data goes here */
+ *   // extra data goes here
  * };
  *
  * static void
@@ -164,7 +164,7 @@ enum {
  * {
  *   MyClosure *my_closure = (MyClosure *)closure;
  *
- *   /* free extra data here */
+ *   // free extra data here
  * }
  *
  * MyClosure *my_closure_new (gpointer data)
@@ -175,7 +175,7 @@ enum {
  *   closure = g_closure_new_simple (sizeof (MyClosure), data);
  *   my_closure = (MyClosure *) closure;
  *
- *   /* initialize extra data here */
+ *   // initialize extra data here
  *
  *   g_closure_add_finalize_notifier (closure, notify_data,
  *                                    my_closure_finalize);
@@ -609,7 +609,7 @@ g_closure_unref (GClosure *closure)
  * |[<!-- language="C" --> 
  * closure = g_cclosure_new (cb_func, cb_data);
  * g_source_set_closure (source, closure);
- * g_closure_unref (closure); /&ast; GObject doesn't really need this &ast;/
+ * g_closure_unref (closure); // GObject doesn't really need this
  * ]|
  * Because g_source_set_closure() (and similar functions) take ownership of the
  * initial reference count, if it is unowned, we instead can write:

gobject/gobject.c

@@ -84,16 +84,18 @@
  * the following sequence can be used:
  *
  * |[<!-- language="C" --> 
- * /&ast; save floating state &ast;/
+ * // save floating state
  * gboolean was_floating = g_object_is_floating (object);
  * g_object_ref_sink (object);
- * /&ast; protected code portion &ast;/
- * ...;
- * /&ast; restore floating state &ast;/
+ * // protected code portion
+ *
+ * ...
+ *
+ * // restore floating state
  * if (was_floating)
  *   g_object_force_floating (object);
  * else
- *   g_object_unref (object); /&ast; release previously acquired reference &ast;/
+ *   g_object_unref (object); // release previously acquired reference
  * ]|
  */
 
@@ -2239,7 +2241,7 @@ g_object_set (gpointer     _object,
  *                "obj-property", &objval,
  *                NULL);
  *
- *  /&ast; Do something with intval, strval, objval &ast;/
+ *  // Do something with intval, strval, objval
  *
  *  g_free (strval);
  *  g_object_unref (objval);

gobject/gvalue.c

@@ -72,37 +72,37 @@
  * main (int   argc,
  *       char *argv[])
  * {
- *   /* GValues must be initialized */
+ *   // GValues must be initialized
  *   GValue a = G_VALUE_INIT;
  *   GValue b = G_VALUE_INIT;
  *   const gchar *message;
  *
- *   /* The GValue starts empty */
+ *   // The GValue starts empty
  *   g_assert (!G_VALUE_HOLDS_STRING (&a));
  *
- *   /* Put a string in it */
+ *   // Put a string in it
  *   g_value_init (&a, G_TYPE_STRING);
  *   g_assert (G_VALUE_HOLDS_STRING (&a));
  *   g_value_set_static_string (&a, "Hello, world!");
  *   g_printf ("%s\n", g_value_get_string (&a));
  *
- *   /* Reset it to its pristine state */
+ *   // Reset it to its pristine state
  *   g_value_unset (&a);
  *
- *   /* It can then be reused for another type */
+ *   // It can then be reused for another type
  *   g_value_init (&a, G_TYPE_INT);
  *   g_value_set_int (&a, 42);
  *
- *   /* Attempt to transform it into a GValue of type STRING */
+ *   // Attempt to transform it into a GValue of type STRING
  *   g_value_init (&b, G_TYPE_STRING);
  *
- *   /* An INT is transformable to a STRING */
+ *   // An INT is transformable to a STRING
  *   g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
  *
  *   g_value_transform (&a, &b);
  *   g_printf ("%s\n", g_value_get_string (&b));
  *
- *   /* Attempt to transform it again using a custom transform function */
+ *   // Attempt to transform it again using a custom transform function
  *   g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
  *   g_value_transform (&a, &b);
  *   g_printf ("%s\n", g_value_get_string (&b));