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

31 files changed, 162 insertions, 175 deletions

diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 08ffaa667..0bae300c1 100644
--- a/gio/gappinfo.c
+++ b/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);
  * ]|
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 9b5d174c8..8ad7a2faa 100644
--- a/gio/gapplicationcommandline.c
+++ b/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),
diff --git a/gio/gcancellable.c b/gio/gcancellable.c
index 6c3254da3..80ebfbfa9 100644
--- a/gio/gcancellable.c
+++ b/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);  
    * ]|
    *
diff --git a/gio/gdbuserror.c b/gio/gdbuserror.c
index 3b40be81a..6308e1772 100644
--- a/gio/gdbuserror.c
+++ b/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
diff --git a/gio/giomodule.c b/gio/giomodule.c
index 219a7399f..ced8a6c60 100644
--- a/gio/giomodule.c
+++ b/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 (),
diff --git a/gio/gmemoryoutputstream.c b/gio/gmemoryoutputstream.c
index a9860795a..740088f9d 100644
--- a/gio/gmemoryoutputstream.c
+++ b/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);
  * ]|
diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c
index 0ec3ef506..610e2fa1d 100644
--- a/gio/gsimpleaction.c
+++ b/gio/gsimpleaction.c
@@ -409,7 +409,7 @@ g_simple_action_class_init (GSimpleActionClass *class)
    *
    *   requested = g_variant_get_int32 (value);
    *
-   *   /&ast; Volume only goes from 0 to 10 &ast;/
+   *   // Volume only goes from 0 to 10
    *   if (0 <= requested && requested <= 10)
    *     g_simple_action_set_state (action, value);
    * }
diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c
index aa413a7ee..63ad6f55c 100644
--- a/gio/gsimpleasyncresult.c
+++ b/gio/gsimpleasyncresult.c
@@ -111,9 +111,8 @@
  * baked_cb (Cake    *cake,
  *           gpointer user_data)
  * {
- *   /&ast; In this example, this callback is not given a reference to the cake, so
- *    &ast; the GSimpleAsyncResult has to take a reference to it.
- *    &ast;/
+ *   // 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);
  *
  *
- *   /&ast; In this example, we assume that baked_cb is called as a callback from
- *    &ast; the mainloop, so it's safe to complete the operation synchronously here.
- *    &ast; If, however, _baker_prepare_cake () might call its callback without
- *    &ast; first returning to the mainloop — inadvisable, but some APIs do so —
- *    &ast; we would need to use g_simple_async_result_complete_in_idle().
- *    &ast;/
+ *   // 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);
- *       /&ast; Drop the reference returned by _baker_get_cached_cake(); the
- *        &ast; GSimpleAsyncResult has taken its own reference.
- *        &ast;/
+ *       // Drop the reference returned by _baker_get_cached_cake();
+ *       // the GSimpleAsyncResult has taken its own reference.
  *       g_object_unref (cake);
  *       return;
  *     }
diff --git a/gio/gsocketconnectable.c b/gio/gsocketconnectable.c
index 46870febb..098ce1c11 100644
--- a/gio/gsocketconnectable.c
+++ b/gio/gsocketconnectable.c
@@ -49,10 +49,9 @@
  *   enumerator = g_socket_connectable_enumerate (addr);
  *   g_object_unref (addr);
  *
- *   /&ast; Try each sockaddr until we succeed. Record the first
- *    &ast; connection error, but not any further ones (since they'll probably
- *    &ast; be basically the same as the first).
- *    &ast;/
+ *   // 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)
  *         {
- *           /&ast; We couldn't connect to the first address, but we succeeded
- *            &ast; in connecting to a later address.
- *            &ast;/
+ *           // 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)
  *     {
- *       /&ast; Either the initial lookup failed, or else the caller
- *        &ast; cancelled us.
- *        &ast;/
+ *       /// Either initial lookup failed, or else the caller cancelled us.
  *       if (conn_error)
  *         g_error_free (conn_error);
  *       return NULL;
diff --git a/gio/gtask.c b/gio/gtask.c
index a4c4088dd..48d8ff52e 100644
--- a/gio/gtask.c
+++ b/gio/gtask.c
@@ -82,7 +82,7 @@
  *       if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
  *         {
  *           g_object_unref (cake);
- *           /&ast; g_task_return_error() takes ownership of error &ast;/
+ *           // 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)
  *         {
- *           /&ast; _baker_get_cached_cake() returns a reffed cake &ast;/
+ *           // _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;
  *         }
  *
- *       /&ast; baking_data_free() will drop its ref on the cake, so
- *        &ast; we have to take another here to give to the caller.
- *        &ast;/
+ *       // 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;
  *
- *       /&ast; Bail out now if the user has already cancelled &ast;/
+ *       // 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);
- *           /&ast; Attach @source to @task's GMainContext and have it call
- *            &ast; decorator_ready() when it is ready.
- *            &ast;/
+ *           // 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;
  *         }
  *
- *       /&ast; If the task has already been cancelled, then we don't
- *        &ast; want to add the cake to the cake cache. Likewise, we don't
- *        &ast; want to have the task get cancelled in the middle of
- *        &ast; updating the cache. g_task_set_return_on_cancel() will
- *        &ast; return %TRUE here if it managed to disable return-on-cancel,
- *        &ast; or %FALSE if the task was cancelled before it could.
- *        &ast;/
+ *       // 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))
  *         {
- *           /&ast; If the caller cancels at this point, their
- *            &ast; GAsyncReadyCallback won't be invoked until we return,
- *            &ast; so we don't have to worry that this code will run at
- *            &ast; the same time as that code does. But if there were
- *            &ast; other functions that might look at the cake cache,
- *            &ast; then we'd probably need a GMutex here as well.
- *            &ast;/
+ *           // 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);
- *       /&ast; ... &ast;/
+ *
+ *       ...
  *
  *       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);
- *       /&ast; ... &ast;/
+ *
+ *       ...
  *
  *       task = g_task_new (self, cancellable, NULL, NULL);
  *       g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
diff --git a/gio/gvolume.c b/gio/gvolume.c
index c25deb7a3..087c9b78f 100644
--- a/gio/gvolume.c
+++ b/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); /&ast; mounted, so never NULL &ast;/
+ *   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); /&ast; assume not NULL &ast;/
+ *   volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
  * ]|
  * then the expression
  * |[<!-- language="C" -->
diff --git a/glib/garray.c b/glib/garray.c
index bb38c6b5e..f81cf0ce3 100644
--- a/glib/garray.c
+++ b/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);
  * ]|
  *
diff --git a/glib/gerror.c b/glib/gerror.c
index 5953b5a82..d0d85238a 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -69,14 +69,14 @@
  * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
  * if (err != NULL)
  *   {
- *     /&ast; Report error to user, and free error &ast;/
+ *     // 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
  *   {
- *     /&ast; Use file contents &ast;/
+ *     // 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);
diff --git a/glib/gfileutils.c b/glib/gfileutils.c
index ebdf8a32e..a18c69892 100644
--- a/glib/gfileutils.c
+++ b/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
  *    }
  * ]|
  *
diff --git a/glib/ghash.c b/glib/ghash.c
index 74b5c70b9..012671d0c 100644
--- a/glib/ghash.c
+++ b/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))
  *   {
- *     /&ast; do something with key and value &ast;/
+ *     // do something with key and value
  *   }
  * ]|
  *
diff --git a/glib/glist.c b/glib/glist.c
index 5a39b5f68..18e25da2d 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -77,7 +77,7 @@
  * GList *l;
  * for (l = list; l != NULL; l = l->next)
  *   {
- *     /&ast; do something with l->data &ast;/
+ *     // do something with l->data
  *   }
  * ]|
  *
@@ -92,7 +92,7 @@
  *     GList *next = l->next;
  *     if (should_be_removed (l))
  *       {
- *         /&ast; possibly free l->data &ast;/
+ *         // 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");
diff --git a/glib/gmain.c b/glib/gmain.c
index 9ddb386fd..6bb726e16 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -2879,7 +2879,7 @@ g_main_current_source (void)
  *   SomeWidget *self = data;
  *    
  *   GDK_THREADS_ENTER ();
- *   /&ast; do stuff with self &ast;/
+ *   // 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 ()))
  *     {
- *       /&ast; do stuff with self &ast;/
+ *       // do stuff with self
  *     }
  *   GDK_THREADS_LEAVE ();
  *   
diff --git a/glib/gmarkup.c b/glib/gmarkup.c
index 4c1fcb00b..d84068a19 100644
--- a/glib/gmarkup.c
+++ b/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);
  *
- *   /&ast; else, handle other tags... &ast;/
+ *   // 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));
  *
- *   /&ast; else, handle other tags... &ast;/
+ *   // else, handle other tags...
  * }
  * ]|
  *
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 5be693463..7288fc4bf 100644
--- a/glib/gmessages.c
+++ b/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");
diff --git a/glib/goption.c b/glib/goption.c
index 7a70ab301..c6497e5ca 100644
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -120,7 +120,7 @@
  *       exit (1);
  *     }
  *
- *   /&ast; ... &ast;/
+ *   ...
  *
  * }
  * ]|
@@ -161,18 +161,18 @@
  *   args = g_strdupv (argv);
  * #endif
  *
- *   /&ast; ... setup context ... &ast;/
+ *   // set up context
  *
  *   if (!g_option_context_parse_strv (context, &args, &error))
  *     {
- *       /&ast; ... error ... &ast;/
+ *       // error happened
  *     }
  *
- *   /&ast; ... &ast;/
+ *   ...
  *
  *   g_strfreev (args);
  *
- *   /&ast; ... &ast;/
+ *   ...
  * }
  * ]|
  */
diff --git a/glib/gregex.c b/glib/gregex.c
index c3740c47d..41bf67e3f 100644
--- a/glib/gregex.c
+++ b/glib/gregex.c
@@ -1643,7 +1643,7 @@ g_regex_match_simple (const gchar        *pattern,
  * static void
  * print_uppercase_words (const gchar *string)
  * {
- *   /&ast; Print all uppercase-only words. &ast;/
+ *   // 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)
  * {
- *   /&ast; Print all uppercase-only words. &ast;/
+ *   // 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;
  * }
  *
- * /&ast; ... &ast;/
+ * ...
  *
  * 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);
  *
- * /&ast; ... &ast;/
+ * ...
  * ]|
  *
  * Returns: a newly allocated string containing the replacements
diff --git a/glib/gslice.c b/glib/gslice.c
index d3a5adca8..0563d8092 100644
--- a/glib/gslice.c
+++ b/glib/gslice.c
@@ -96,17 +96,17 @@
  * gchar *mem[10000];
  * gint i;
  *
- * /&ast; Allocate 10000 blocks. &ast;/
+ * // 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);
  * ]|
  */
diff --git a/glib/gslist.c b/glib/gslist.c
index fc4f8655d..83c0449aa 100644
--- a/glib/gslist.c
+++ b/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");
diff --git a/glib/gtestutils.c b/glib/gtestutils.c
index 0b9aef9cb..002c2aef1 100644
--- a/glib/gtestutils.c
+++ b/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); /&ast; successful test run &ast;/
+ *         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;
  *       }
  *
- *     /&ast; Reruns this same test in a subprocess &ast;/
+ *     // 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*");
diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c
index 5ead8f16e..374cdede7 100644
--- a/glib/gthread-posix.c
+++ b/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))
  *       {
- *         /&ast; timeout has passed. &ast;/
+ *         // timeout has passed.
  *         g_mutex_unlock (&data_mutex);
  *         return NULL;
  *       }
  *
- *   /&ast; there is data for us &ast;/
+ *   // 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)
diff --git a/glib/gthread.c b/glib/gthread.c
index dce98a070..ea8e5f965 100644
--- a/glib/gthread.c
+++ b/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;
  *
- *     /&ast; now do a very complicated calculation to calculate the new
- *      &ast; number, this might for example be a random number generator
- *      &ast;/
+ *     // 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; /&ast; initialization code here &ast;/
+ *       gsize setup_value = 42; // initialization code here
  *
  *       g_once_init_leave (&initialization_value, setup_value);
  *     }
  *
- *   /&ast; use initialization_value here &ast;/
+ *   // use initialization_value here
  * ]|
  *
  * Returns: %TRUE if the initialization section should be entered,
diff --git a/glib/gvariant.c b/glib/gvariant.c
index daf7db9bb..379844b1f 100644
--- a/glib/gvariant.c
+++ b/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
  *       }
  *   }
  * ]|
diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c
index 85d5c5484..bf1eac73e 100644
--- a/gmodule/gmodule.c
+++ b/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))
diff --git a/gobject/gclosure.c b/gobject/gclosure.c
index c28f84150..02e9d8685 100644
--- a/gobject/gclosure.c
+++ b/gobject/gclosure.c
@@ -155,7 +155,7 @@ enum {
  * struct _MyClosure
  * {
  *   GClosure closure;
- *   /&ast; extra data goes here &ast;/
+ *   // extra data goes here
  * };
  *
  * static void
@@ -164,7 +164,7 @@ enum {
  * {
  *   MyClosure *my_closure = (MyClosure *)closure;
  *
- *   /&ast; free extra data here &ast;/
+ *   // 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;
  *
- *   /&ast; initialize extra data here &ast;/
+ *   // 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:
diff --git a/gobject/gobject.c b/gobject/gobject.c
index 6be1e8435..29bcccd68 100644
--- a/gobject/gobject.c
+++ b/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);
diff --git a/gobject/gvalue.c b/gobject/gvalue.c
index 87fdd4b9d..6a0031c0b 100644
--- a/gobject/gvalue.c
+++ b/gobject/gvalue.c
@@ -72,37 +72,37 @@
  * main (int   argc,
  *       char *argv[])
  * {
- *   /&ast; GValues must be initialized &ast;/
+ *   // GValues must be initialized
  *   GValue a = G_VALUE_INIT;
  *   GValue b = G_VALUE_INIT;
  *   const gchar *message;
  *
- *   /&ast; The GValue starts empty &ast;/
+ *   // The GValue starts empty
  *   g_assert (!G_VALUE_HOLDS_STRING (&a));
  *
- *   /&ast; Put a string in it &ast;/
+ *   // 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));
  *
- *   /&ast; Reset it to its pristine state &ast;/
+ *   // Reset it to its pristine state
  *   g_value_unset (&a);
  *
- *   /&ast; It can then be reused for another type &ast;/
+ *   // It can then be reused for another type
  *   g_value_init (&a, G_TYPE_INT);
  *   g_value_set_int (&a, 42);
  *
- *   /&ast; Attempt to transform it into a GValue of type STRING &ast;/
+ *   // Attempt to transform it into a GValue of type STRING
  *   g_value_init (&b, G_TYPE_STRING);
  *
- *   /&ast; An INT is transformable to a STRING &ast;/
+ *   // 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));
  *
- *   /&ast; Attempt to transform it again using a custom transform function &ast;/
+ *   // 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));