Docs: Big entity cleanup

Strip lots of entity use from |[ ]| examples (which are now
implicit CDATA). Also remove many redundant uses of <!-- -->.

gio/gappinfo.c

@@ -121,7 +121,7 @@ g_app_info_dup (GAppInfo *appinfo)
  * @appinfo1: the first #GAppInfo.
  * @appinfo2: the second #GAppInfo.
  *
- * Checks if two #GAppInfo<!-- -->s are equal.
+ * Checks if two #GAppInfos are equal.
  *
  * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
  **/
@@ -760,8 +760,8 @@ g_app_info_can_delete (GAppInfo *appinfo)
  * Tries to delete a #GAppInfo.
  *
  * On some platforms, there may be a difference between user-defined
- * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
+ * #GAppInfos which can be deleted, and system-wide ones which cannot.
- * cannot. See g_app_info_can_delete().
+ * See g_app_info_can_delete().
  *
  * Virtual: do_delete
  * Returns: %TRUE if @appinfo has been deleted

gio/gasyncresult.c

@@ -81,20 +81,20 @@
  *   else
  *     g_printf ("Uh oh!\n");
  *
- *   /<!-- -->* ... *<!-- -->/
+ *   ...
  *
  * }
  *
  * int main (int argc, void *argv[])
  * {
- *    /<!-- -->* ... *<!-- -->/
+ *    ...
  *
  *    _theoretical_frobnitz_async (theoretical_data,
  *                                 NULL,
  *                                 frobnitz_result_func,
  *                                 NULL);
  *
- *    /<!-- -->* ... *<!-- -->/
+ *    ...
  * }
  * ]|
  *

gio/gcancellable.c

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

gio/gdbusconnection.c

@@ -5908,7 +5908,7 @@ g_dbus_connection_call_finish (GDBusConnection  *connection,
  *                               G_DBUS_CALL_FLAGS_NONE,
  *                               -1,
  *                               NULL,
- *                               &error);
+ *                               &error);
  * ]|
  *
  * The calling thread is blocked until a reply is received. See

gio/gdbuserror.c

@@ -336,7 +336,7 @@ static GHashTable *dbus_error_name_to_re = NULL;
  * @dbus_error_name: A D-Bus error name.
  *
  * Creates an association to map between @dbus_error_name and
- * #GError<!-- -->s specified by @error_domain and @error_code.
+ * #GErrors specified by @error_domain and @error_code.
  *
  * This is typically done in the routine that returns the #GQuark for
  * an error domain.
@@ -490,16 +490,17 @@ g_dbus_error_is_remote_error (const GError *error)
 
 /**
  * g_dbus_error_get_remote_error:
- * @error: A #GError.
+ * @error: a #GError
  *
  * Gets the D-Bus error name used for @error, if any.
  *
  * This function is guaranteed to return a D-Bus error name for all
- * #GError<!-- -->s returned from functions handling remote method
+ * #GErrors returned from functions handling remote method calls
- * calls (e.g. g_dbus_connection_call_finish()) unless
+ * (e.g. g_dbus_connection_call_finish()) unless
  * g_dbus_error_strip_remote_error() has been used on @error.
  *
- * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
+ * Returns: an allocated string or %NULL if the D-Bus error name
+ *     could not be found. Free with g_free().
  *
  * Since: 2.26
  */

gio/gdbusmessage.c

@@ -3350,32 +3350,32 @@ _sort_keys_func (gconstpointer a,
  * and formatting is subject to change at any time. Typical output
  * looks something like this:
  * |[
- * Type:    method-call
+ * Type:    method-call
- * Flags:   none
+ * Flags:   none
- * Version: 0
+ * Version: 0
- * Serial:  4
+ * Serial:  4
- * Headers:
+ * Headers:
  *   path -> objectpath '/org/gtk/GDBus/TestObject'
  *   interface -> 'org.gtk.GDBus.TestInterface'
  *   member -> 'GimmeStdout'
  *   destination -> ':1.146'
- * Body: ()
+ * Body: ()
  * UNIX File Descriptors:
  *   (none)
  * ]|
  * or
  * |[
- * Type:    method-return
+ * Type:    method-return
- * Flags:   no-reply-expected
+ * Flags:   no-reply-expected
- * Version: 0
+ * Version: 0
- * Serial:  477
+ * Serial:  477
- * Headers:
+ * Headers:
  *   reply-serial -> uint32 4
  *   destination -> ':1.159'
  *   sender -> ':1.146'
  *   num-unix-fds -> uint32 1
- * Body: ()
+ * Body: ()
- * UNIX File Descriptors:
+ * UNIX File Descriptors:
  *   fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
  * ]|
  *

gio/gdbusobjectmanagerserver.c

@@ -541,10 +541,9 @@ g_dbus_object_manager_server_export (GDBusObjectManagerServer  *manager,
  * @object: An object.
  *
  * Like g_dbus_object_manager_server_export() but appends a string of
- * the form <literal>_N</literal> (with N being a natural number) to
+ * the form _N (with N being a natural number) to @object's object path
- * @object<!-- -->'s object path if an object with the given path
+ * if an object with the given path already exists. As such, the
- * already exists. As such, the #GDBusObjectProxy:g-object-path property
+ * #GDBusObjectProxy:g-object-path property of @object may be modified.
- * of @object may be modified.
  *
  * Since: 2.30
  */

gio/gdbusobjectskeleton.c

@@ -173,9 +173,9 @@ g_dbus_object_skeleton_class_init (GDBusObjectSkeletonClass *klass)
    * Emitted when a method is invoked by a remote caller and used to
    * determine if the method call is authorized.
    *
-   * This signal is like #GDBusInterfaceSkeleton<!-- -->'s
+   * This signal is like #GDBusInterfaceSkeleton's
-   * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
+   * #GDBusInterfaceSkeleton::g-authorize-method signal,
-   * for the enclosing object.
+   * except that it is for the enclosing object.
    *
    * The default class handler just returns %TRUE.
    *

gio/gdbusproxy.c

@@ -2976,7 +2976,7 @@ g_dbus_proxy_call_sync_internal (GDBusProxy      *proxy,
  *                     -1,
  *                     NULL,
  *                     (GAsyncReadyCallback) two_strings_done,
- *                     &data);
+ *                     &data);
  * ]|
  *
  * If @proxy has an expected interface (see
@@ -3066,7 +3066,7 @@ g_dbus_proxy_call_finish (GDBusProxy    *proxy,
  *                          G_DBUS_CALL_FLAGS_NONE,
  *                          -1,
  *                          NULL,
- *                          &error);
+ *                          &error);
  * ]|
  *
  * The calling thread is blocked until a reply is received. See

gio/gemblemedicon.c

@@ -196,7 +196,7 @@ g_emblemed_icon_get_icon (GEmblemedIcon *emblemed)
  * Gets the list of emblems for the @icon.
  *
  * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
- *          #GEmblem <!-- -->s that is owned by @emblemed
+ *     #GEmblems that is owned by @emblemed
  *
  * Since: 2.18
  **/
@@ -250,7 +250,7 @@ g_emblem_comp (GEmblem *a,
  * @emblemed: a #GEmblemedIcon
  * @emblem: a #GEmblem
  *
- * Adds @emblem to the #GList of #GEmblem <!-- -->s.
+ * Adds @emblem to the #GList of #GEmblems.
  *
  * Since: 2.18
  **/

gio/gfileenumerator.c

@@ -41,7 +41,7 @@ struct _GFileEnumeratorPrivate {
  * @short_description: Enumerated Files Routines
  * @include: gio/gio.h
  * 
- * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, 
+ * #GFileEnumerator allows you to operate on a set of #GFiles, 
  * returning a #GFileInfo structure for each file enumerated (e.g. 
  * g_file_enumerate_children() will return a #GFileEnumerator for each 
  * of the children within a directory).
@@ -49,7 +49,7 @@ struct _GFileEnumeratorPrivate {
  * To get the next file's information from a #GFileEnumerator, use 
  * g_file_enumerator_next_file() or its asynchronous version, 
  * g_file_enumerator_next_files_async(). Note that the asynchronous 
- * version will return a list of #GFileInfo<!---->s, whereas the 
+ * version will return a list of #GFileInfos, whereas the 
  * synchronous will only return the next file in the enumerator.
  *
  * The ordering of returned files is unspecified for non-Unix

gio/gfileinfo.c

@@ -2285,7 +2285,7 @@ matcher_optimize (GFileAttributeMatcher *matcher)
  * @attributes: an attribute string to match.
  *
  * Creates a new file attribute matcher, which matches attributes
- * against a given string. #GFileAttributeMatcher<!-- -->s are reference
+ * against a given string. #GFileAttributeMatchers are reference
  * counted structures, and are created with a reference count of 1. If
  * the number of references falls to 0, the #GFileAttributeMatcher is
  * automatically destroyed.

gio/giomodule.c

@@ -1227,8 +1227,8 @@ lazy_load_modules (GIOExtensionPoint *extension_point)
  * The list is sorted by priority, beginning with the highest priority.
  *
  * Returns: (element-type GIOExtension) (transfer none): a #GList of
- * #GIOExtension<!-- -->s. The list is owned by GIO and should not be
+ *     #GIOExtensions. The list is owned by GIO and should not be
- * modified.
+ *     modified.
  */
 GList *
 g_io_extension_point_get_extensions (GIOExtensionPoint *extension_point)

gio/gsettings.c

@@ -637,7 +637,7 @@ g_settings_class_init (GSettingsClass *class)
    * GSettings::change-event:
    * @settings: the object on which the signal was emitted
    * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
-   *        an array of #GQuark<!-- -->s for the changed keys, or %NULL
+   *        an array of #GQuarks for the changed keys, or %NULL
    * @n_keys: the length of the @keys array, or 0
    *
    * The "change-event" signal is emitted once per change event that

gio/gsimpleasyncresult.c

@@ -41,7 +41,7 @@
  *
  * #GSimpleAsyncResult implements #GAsyncResult.
  *
- * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
+ * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
  * reporting, operation cancellation and the final state of an operation,
  * completely transparent to the application. Results can be returned
  * as a pointer e.g. for functions that return data that is collected
@@ -79,7 +79,7 @@
  * cause a leak if cancelled before being run).
  *
  * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
- * or it can use #GThread<!-- -->s.
+ * or it can use #GThreads.
  * g_simple_async_result_complete() will finish an I/O task directly
  * from the point where it is called. g_simple_async_result_complete_in_idle()
  * will finish it from an idle handler in the <link

gio/gsocket.c

@@ -103,7 +103,7 @@
  * reasons. For instance, on Windows a socket is always seen as writable
  * until a write returns %G_IO_ERROR_WOULD_BLOCK.
  *
- * #GSocket<!-- -->s can be either connection oriented or datagram based.
+ * #GSockets can be either connection oriented or datagram based.
  * For connection oriented types you must first establish a connection by
  * either connecting to an address or accepting a connection from another
  * address. For connectionless socket types the target/source address is
@@ -3708,7 +3708,7 @@ g_socket_condition_timed_wait (GSocket       *socket,
  * then @vectors is assumed to be terminated by a #GOutputVector with a
  * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
  * that the sent data will be gathered from. Using multiple
- * #GOutputVector<!-- -->s is more memory-efficient than manually copying
+ * #GOutputVectors is more memory-efficient than manually copying
  * data from multiple sources into a single buffer, and more
  * network-efficient than making multiple calls to g_socket_send().
  *

gio/gsocketconnectable.c

@@ -49,10 +49,10 @@
  *   enumerator = g_socket_connectable_enumerate (addr);
  *   g_object_unref (addr);
  *
- *   /<!-- -->* Try each sockaddr until we succeed. Record the first
+ *   /&ast; Try each sockaddr until we succeed. Record the first
- *    * connection error, but not any further ones (since they'll probably
+ *    &ast; connection error, but not any further ones (since they'll probably
- *    * be basically the same as the first).
+ *    &ast; be basically the same as the first).
- *    *<!-- -->/
+ *    &ast;/
  *   while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
  *     {
  *       conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
@@ -64,18 +64,18 @@
  *     {
  *       if (conn_error)
  *         {
- *           /<!-- -->* We couldn't connect to the first address, but we succeeded
+ *           /&ast; We couldn't connect to the first address, but we succeeded
- *            * in connecting to a later address.
+ *            &ast; in connecting to a later address.
- *            *<!-- -->/
+ *            &ast;/
  *           g_error_free (conn_error);
  *         }
  *       return conn;
  *     }
  *   else if (error)
  *     {
- *       /<!-- -->* Either the initial lookup failed, or else the caller
+ *       /&ast; Either the initial lookup failed, or else the caller
- *        * cancelled us.
+ *        &ast; cancelled us.
- *        *<!-- -->/
+ *        &ast;/
  *       if (conn_error)
  *         g_error_free (conn_error);
  *       return NULL;
@@ -125,7 +125,7 @@ g_socket_connectable_enumerate (GSocketConnectable *connectable)
  * @connectable: a #GSocketConnectable
  *
  * Creates a #GSocketAddressEnumerator for @connectable that will
- * return #GProxyAddress<!-- -->es for addresses that you must connect
+ * return #GProxyAddresses for addresses that you must connect
  * to via a proxy.
  *
  * If @connectable does not implement

gio/gsrvtarget.c

@@ -42,7 +42,7 @@
  * then connect to whatever host was pointed to by that record.
  *
  * You can use g_resolver_lookup_service() or
- * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
+ * g_resolver_lookup_service_async() to find the #GSrvTargets
  * for a given service. However, if you are simply planning to connect
  * to the remote service, you can use #GNetworkService's
  * #GSocketConnectable interface and not need to worry about
@@ -75,7 +75,7 @@ G_DEFINE_BOXED_TYPE (GSrvTarget, g_srv_target,
  *
  * Creates a new #GSrvTarget with the given parameters.
  *
- * You should not need to use this; normally #GSrvTarget<!-- -->s are
+ * You should not need to use this; normally #GSrvTargets are
  * created by #GResolver.
  *
  * Return value: a new #GSrvTarget.

gio/gtlscertificate.c

@@ -446,7 +446,7 @@ g_tls_certificate_new_from_files (const gchar  *cert_file,
  * @file: file containing PEM-encoded certificates to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
+ * Creates one or more #GTlsCertificates from the PEM-encoded
  * data in @file. If @file cannot be read or parsed, the function will
  * return %NULL and set @error. If @file does not contain any
  * PEM-encoded certificates, this will return an empty list and not

glib/docs.c

@@ -278,7 +278,7 @@
  * |[
  * gint16 in;
  * gint32 out;
- * sscanf ("42", "%" G_GINT16_FORMAT, &in)
+ * sscanf ("42", "%" G_GINT16_FORMAT, &in)
  * out = in * 1000;
  * g_print ("%" G_GINT32_FORMAT, out);
  * ]|

glib/garray.c

@@ -75,11 +75,11 @@
  *    * 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++)
+ *   for (i = 0; i < 10000; i++)
  *     g_array_append_val (garray, i);
- *   for (i = 0; i &lt; 10000; i++)
+ *   for (i = 0; i < 10000; i++)
  *     if (g_array_index (garray, gint, i) != i)
- *       g_print ("ERROR: got &percnt;d instead of &percnt;d\n",
+ *       g_print ("ERROR: got %d instead of %d\n",
  *                g_array_index (garray, gint, i), i);
  *   g_array_free (garray, TRUE);
  * ]|
@@ -125,7 +125,7 @@ struct _GRealArray
  *   /&ast; This gets a pointer to the 4th element
  *    &ast; in the array of EDayViewEvent structs.
  *    &ast;/
- *   event = &amp;g_array_index (events, EDayViewEvent, 3);
+ *   event = &g_array_index (events, EDayViewEvent, 3);
  * ]|
  *
  * Returns: the element of the #GArray at the index given by @i

glib/gbacktrace.c

@@ -102,7 +102,7 @@ volatile gboolean glib_on_error_halt = TRUE;
  * the g_log() functions.
  *
  * |[
- * #include <glib.h>
+ * #include <glib.h>
  *
  * static void
  * log_handler (const gchar   *log_domain,
@@ -124,7 +124,7 @@ volatile gboolean glib_on_error_halt = TRUE;
  *                      G_LOG_LEVEL_CRITICAL,
  *                      log_handler,
  *                      NULL);
- *   /&ast; ... &ast;/
+ *   ...
  * ]|
  *
  * If [E]xit is selected, the application terminates with a call

glib/gbookmarkfile.c

@@ -79,7 +79,9 @@
  * the bookmark as "private" to the applications and groups that has it
  * registered; the URI and MIME type of an icon, to be used when displaying
  * the bookmark inside a GUI.
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>
+ * </programlisting>
  *
  * A bookmark file might contain more than one bookmark; each bookmark
  * is accessed through its URI.

glib/gdate.c

@@ -165,7 +165,7 @@
  * time_t ttime;
  * GTime gtime;
  *
- * time (&ttime);
+ * time (&ttime);
  * gtime = (GTime)ttime;
  * ]|
  */

glib/gerror.c

@@ -65,13 +65,14 @@
  * |[
  * gchar *contents;
  * GError *err = NULL;
- * g_file_get_contents ("foo.txt", &contents, NULL, &err);
+ *
- * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
+ * g_file_get_contents ("foo.txt", &contents, NULL, &err);
+ * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
  * if (err != NULL)
  *   {
  *     /* Report error to user, and free error */
  *     g_assert (contents == NULL);
- *     fprintf (stderr, "Unable to read file: %s\n", err->message);
+ *     fprintf (stderr, "Unable to read file: %s\n", err->message);
  *     g_error_free (err);
  *   }
  * else
@@ -89,7 +90,7 @@
  * are only interested in whether it failed and don't need to display
  * an error message, you can pass %NULL for the @error argument:
  * |[
- * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
+ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
  *   /* no error occurred */ ;
  * else
  *   /* error */ ;
@@ -122,12 +123,12 @@
  *
  *   fd = open ("file.txt", O_RDONLY);
  *
- *   if (fd < 0)
+ *   if (fd < 0)
  *     {
  *       g_set_error (error,
  *                    FOO_ERROR,                 /&ast; error domain &ast;/
  *                    FOO_ERROR_BLAH,            /&ast; error code &ast;/
- *                    "Failed to open file: &percnt;s", /&ast; error message format string &ast;/
+ *                    "Failed to open file: %s", /&ast; error message format string &ast;/
  *                    g_strerror (errno));
  *       return -1;
  *     }
@@ -171,7 +172,7 @@
  *   g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
  *
  *   tmp_error = NULL;
- *   sub_function_that_can_fail (&amp;tmp_error);
+ *   sub_function_that_can_fail (&tmp_error);
  *
  *   if (tmp_error != NULL)
  *     {
@@ -196,8 +197,8 @@
  *   g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
  *
  *   tmp_error = NULL;
- *   sub_function_that_can_fail (&amp;tmp_error);
+ *   sub_function_that_can_fail (&tmp_error);
- *   other_function_that_can_fail (&amp;tmp_error);
+ *   other_function_that_can_fail (&tmp_error);
  *
  *   if (tmp_error != NULL)
  *     {
@@ -225,7 +226,7 @@
  *   sub_function_that_can_fail (NULL); /&ast; ignore errors &ast;/
  *
  *   tmp_error = NULL;
- *   other_function_that_can_fail (&amp;tmp_error);
+ *   other_function_that_can_fail (&tmp_error);
  *
  *   if (tmp_error != NULL)
  *     {

glib/ggettext.c

@@ -477,8 +477,8 @@ g_dngettext (const gchar *domain,
  * <filename>glib/gi18n-lib.h</filename> after defining the %GETTEXT_PACKAGE
  * macro suitably for your library:
  * |[
- * &num;define GETTEXT_PACKAGE "gtk20"
+ * #define GETTEXT_PACKAGE "gtk20"
- * &num;include &lt;glib/gi18n-lib.h&gt;
+ * #include <glib/gi18n-lib.h>
  * ]|
  * For an application, note that you also have to call bindtextdomain(),
  * bind_textdomain_codeset(), textdomain() and setlocale() early on in your
@@ -602,8 +602,8 @@ g_dngettext (const gchar *domain,
  *   const char *string;
  *   ...
  *   string
- *     = index &gt; 1 ? g_dpgettext2 (NULL, "some context", "a default message")
+ *     = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
- *                    : g_dpgettext2 (NULL, "some context", messages[index]);
+ *                 : g_dpgettext2 (NULL, "some context", messages[index]);
  *
  *   fputs (string);
  *   ...

glib/gmain.c

@@ -772,7 +772,7 @@ g_main_context_pop_thread_default (GMainContext *context)
  * operations that want to be able to be run in contexts other than
  * the default one should call this method or
  * g_main_context_ref_thread_default() to get a #GMainContext to add
- * their #GSource<!-- -->s to. (Note that even in single-threaded
+ * their #GSources to. (Note that even in single-threaded
  * programs applications may sometimes want to temporarily push a
  * non-default context, so it is not safe to assume that this will
  * always return %NULL if you are running in the default thread.)
@@ -2873,10 +2873,10 @@ g_main_current_source (void)
  * {
  *   SomeWidget *self = data;
  *    
- *   GDK_THREADS_ENTER (<!-- -->);
+ *   GDK_THREADS_ENTER ();
- *   /<!-- -->* do stuff with self *<!-- -->/
+ *   /&ast; do stuff with self &ast;/
  *   self->idle_id = 0;
- *   GDK_THREADS_LEAVE (<!-- -->);
+ *   GDK_THREADS_LEAVE ();
  *    
  *   return G_SOURCE_REMOVE;
  * }
@@ -2914,7 +2914,7 @@ g_main_current_source (void)
  *   GDK_THREADS_ENTER ();
  *   if (!g_source_is_destroyed (g_main_current_source ()))
  *     {
- *       /<!-- -->* do stuff with self *<!-- -->/
+ *       /&ast; do stuff with self &ast;/
  *     }
  *   GDK_THREADS_LEAVE ();
  *   

glib/gmarkup.c

@@ -2524,14 +2524,14 @@ g_markup_vprintf_escaped (const gchar *format,
  * might themselves contain markup.
  *
  * |[
- * const char *store = "Fortnum & Mason";
+ * const char *store = "Fortnum & Mason";
  * const char *item = "Tea";
  * char *output;
- *  
+ * 
- * output = g_markup_printf_escaped ("<purchase>"
+ * output = g_markup_printf_escaped ("<purchase>"
- *                                   "&lt;store&gt;&percnt;s&lt;/store&gt;"
+ *                                   "<store>%s</store>"
- *                                   "&lt;item&gt;&percnt;s&lt;/item&gt;"
+ *                                   "<item>%s</item>"
- *                                   "&lt;/purchase&gt;",
+ *                                   "</purchase>",
  *                                   store, item);
  * ]|
  *

glib/goption.c

@@ -77,7 +77,7 @@
  *   --rand                   Randomize the data
  * </screen></informalexample>
  *
- * GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
+ * GOption groups options in #GOptionGroups, which makes it easy to
  * incorporate options from multiple sources. The intended use for this is
  * to let applications collect option groups from the libraries it uses,
  * add them to their #GOptionContext, and parse all options by a single call
@@ -581,7 +581,7 @@ g_option_context_get_main_group (GOptionContext *context)
 /**
  * g_option_context_add_main_entries:
  * @context: a #GOptionContext
- * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ * @entries: a %NULL-terminated array of #GOptionEntrys
  * @translation_domain: (allow-none): a translation domain to use for translating
  *    the <option>--help</option> output for the options in @entries
  *    with gettext(), or %NULL
@@ -2227,7 +2227,7 @@ g_option_group_free (GOptionGroup *group)
 /**
  * g_option_group_add_entries:
  * @group: a #GOptionGroup
- * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ * @entries: a %NULL-terminated array of #GOptionEntrys
  *
  * Adds the options specified in @entries to @group.
  *
@@ -2339,7 +2339,7 @@ g_option_group_set_error_hook (GOptionGroup     *group,
  *
  * Sets the function which is used to translate user-visible
  * strings, for <option>--help</option> output. Different
- * groups can use different #GTranslateFunc<!-- -->s. If @func
+ * groups can use different #GTranslateFuncs. If @func
  * is %NULL, strings are not translated.
  *
  * If you are using gettext(), you only need to set the translation

glib/gpoll.c

@@ -108,7 +108,7 @@ extern gboolean _g_main_poll_debug;
  * file descriptor, but the situation is much more complicated on
  * Windows. If you need to use g_poll() in code that has to run on
  * Windows, the easiest solution is to construct all of your
- * #GPollFD<!-- -->s with g_io_channel_win32_make_pollfd().
+ * #GPollFDs with g_io_channel_win32_make_pollfd().
  *
  * Return value: the number of entries in @fds whose %revents fields
  * were filled in, or 0 if the operation timed out, or -1 on error or

glib/gquark.c

@@ -98,7 +98,7 @@ static gint           quark_block_offset = 0;
  *
  * A convenience macro which defines a function returning the
  * #GQuark for the name @QN. The function will be named
- * @q_n<!-- -->_quark().
+ * @q_n_quark().
  *
  * Note that the quark name will be stringified automatically
  * in the macro, so you shouldn't use double quotes.

glib/gregex.c

@@ -960,7 +960,7 @@ g_match_info_expand_references (const GMatchInfo  *match_info,
  * @match_info: #GMatchInfo structure
  * @match_num: number of the sub expression
  *
- * Retrieves the text matching the @match_num<!-- -->'th capturing
+ * Retrieves the text matching the @match_num'th capturing
  * parentheses. 0 is the full text of the match, 1 is the first paren
  * set, 2 the second, and so on.
  *
@@ -1015,7 +1015,7 @@ g_match_info_fetch (const GMatchInfo *match_info,
  * @end_pos: (out) (allow-none): pointer to location where to store
  *     the end position, or %NULL
  *
- * Retrieves the position in bytes of the @match_num<!-- -->'th capturing
+ * Retrieves the position in bytes of the @match_num'th capturing
  * parentheses. 0 is the full text of the match, 1 is the first
  * paren set, 2 the second, and so on.
  *
@@ -1645,9 +1645,9 @@ g_regex_match_simple (const gchar        *pattern,
  *   /&ast; Print all uppercase-only words. &ast;/
  *   GRegex *regex;
  *   GMatchInfo *match_info;
- *   &nbsp;
+ *  
  *   regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- *   g_regex_match (regex, string, 0, &amp;match_info);
+ *   g_regex_match (regex, string, 0, &match_info);
  *   while (g_match_info_matches (match_info))
  *     {
  *       gchar *word = g_match_info_fetch (match_info, 0);
@@ -1719,15 +1719,15 @@ g_regex_match (const GRegex      *regex,
  *   GRegex *regex;
  *   GMatchInfo *match_info;
  *   GError *error = NULL;
- *   &nbsp;
+ *   
  *   regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- *   g_regex_match_full (regex, string, -1, 0, 0, &amp;match_info, &amp;error);
+ *   g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
  *   while (g_match_info_matches (match_info))
  *     {
  *       gchar *word = g_match_info_fetch (match_info, 0);
  *       g_print ("Found: %s\n", word);
  *       g_free (word);
- *       g_match_info_next (match_info, &amp;error);
+ *       g_match_info_next (match_info, &error);
  *     }
  *   g_match_info_free (match_info);
  *   g_regex_unref (regex);

glib/gstrfuncs.c

@@ -269,7 +269,7 @@
  * |[
  *   char buf[G_ASCII_DTOSTR_BUF_SIZE];
  *
- *   fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
+ *   fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
  * ]|
  */
 

glib/gthread.c

@@ -252,9 +252,9 @@
  *     static int current_number = 0;
  *     int ret_val;
  *
- *     g_mutex_lock (&mutex);
+ *     g_mutex_lock (&mutex);
  *     ret_val = current_number = calc_next_number (current_number);
- *     g_mutex_unlock (&mutex);
+ *     g_mutex_unlock (&mutex);
  *
  *     return ret_val;
  *   }
@@ -320,10 +320,10 @@
  *     if (!array)
  *       return NULL;
  *
- *     g_rw_lock_reader_lock (&lock);
+ *     g_rw_lock_reader_lock (&lock);
  *     if (index < array->len)
  *       retval = g_ptr_array_index (array, index);
- *     g_rw_lock_reader_unlock (&amp;lock);
+ *     g_rw_lock_reader_unlock (&lock);
  *
  *     return retval;
  *   }
@@ -618,14 +618,14 @@ g_once_impl (GOnce       *once,
  * |[
  *   static gsize initialization_value = 0;
  *
- *   if (g_once_init_enter (&amp;initialization_value))
+ *   if (g_once_init_enter (&initialization_value))
  *     {
- *       gsize setup_value = 42; /&ast;* initialization code here *&ast;/
+ *       gsize setup_value = 42; /&ast; initialization code here &ast;/
  *
- *       g_once_init_leave (&amp;initialization_value, setup_value);
+ *       g_once_init_leave (&initialization_value, setup_value);
  *     }
  *
- *   /&ast;* use initialization_value here *&ast;/
+ *   /&ast; use initialization_value here &ast;/
  * ]|
  *
  * Returns: %TRUE if the initialization section should be entered,

gobject/gclosure.c

@@ -43,13 +43,13 @@
  * A #GClosure represents a callback supplied by the programmer. It
  * will generally comprise a function of some kind and a marshaller
  * used to call it. It is the reponsibility of the marshaller to
- * convert the arguments for the invocation from #GValue<!-- -->s into
+ * convert the arguments for the invocation from #GValues into
  * a suitable form, perform the callback on the converted arguments,
  * and transform the return value back into a #GValue.
  *
  * In the case of C programs, a closure usually just holds a pointer
  * to a function and maybe a data argument, and the marshaller
- * converts between #GValue<!-- --> and native C types. The GObject
+ * converts between #GValue and native C types. The GObject
  * library provides the #GCClosure type for this purpose. Bindings for
  * other languages need marshallers which convert between #GValue<!--
  * -->s and suitable representations in the runtime of the language in
@@ -156,7 +156,7 @@ enum {
  * struct _MyClosure
  * {
  *   GClosure closure;
- *   // extra data goes here
+ *   /&ast; extra data goes here &ast;/
  * };
  *
  * static void
@@ -165,7 +165,7 @@ enum {
  * {
  *   MyClosure *my_closure = (MyClosure *)closure;
  *
- *   // free extra data here
+ *   /&ast; free extra data here &ast;/
  * }
  *
  * MyClosure *my_closure_new (gpointer data)
@@ -176,7 +176,7 @@ enum {
  *   closure = g_closure_new_simple (sizeof (MyClosure), data);
  *   my_closure = (MyClosure *) closure;
  *
- *   // initialize extra data here
+ *   /&ast; initialize extra data here &ast;/
  *
  *   g_closure_add_finalize_notifier (closure, notify_data,
  *                                    my_closure_finalize);
@@ -611,7 +611,7 @@ g_closure_unref (GClosure *closure)
  * |[
  * closure = g_cclosure_new (cb_func, cb_data);
  * g_source_set_closure (source, closure);
- * g_closure_unref (closure); // XXX GObject doesn't really need this
+ * g_closure_unref (closure); /&ast; GObject doesn't really need this &ast;/
  * ]|
  * Because g_source_set_closure() (and similar functions) take ownership of the
  * initial reference count, if it is unowned, we instead can write:
@@ -726,7 +726,7 @@ g_closure_remove_finalize_notifier (GClosure      *closure,
  *                doesn't return a value.
  * @n_param_values: the length of the @param_values array
  * @param_values: (array length=n_param_values): an array of
- *                #GValue<!-- -->s holding the arguments on which to
+ *                #GValues holding the arguments on which to
  *                invoke the callback of @closure
  * @invocation_hint: (allow-none): a context-dependent invocation hint
  *
@@ -1360,7 +1360,7 @@ va_to_ffi_type (GType gtype,
  * @return_gvalue: A #GValue to store the return value. May be %NULL
  *   if the callback of closure doesn't return a value.
  * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValue<!-- -->s holding the arguments
+ * @param_values: An array of #GValues holding the arguments
  *   on which to invoke the callback of closure.
  * @invocation_hint: The invocation hint given as the last argument to
  *   g_closure_invoke().

gobject/gobject.c

@@ -572,11 +572,11 @@ g_object_class_install_property (GObjectClass *class,
 /**
  * g_object_class_install_properties:
  * @oclass: a #GObjectClass
- * @n_pspecs: the length of the #GParamSpec<!-- -->s array
+ * @n_pspecs: the length of the #GParamSpecs array
- * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array
+ * @pspecs: (array length=n_pspecs): the #GParamSpecs array
  *   defining the new properties
  *
- * Installs new properties from an array of #GParamSpec<!-- -->s. This is
+ * Installs new properties from an array of #GParamSpecs. This is
  * usually done in the class initializer.
  *
  * The property id of each property is the index of each #GParamSpec in
@@ -586,7 +586,7 @@ g_object_class_install_property (GObjectClass *class,
  * be used to store a #GParamSpec.
  *
  * This function should be used if you plan to use a static array of
- * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this
+ * #GParamSpecs and g_object_notify_by_pspec(). For instance, this
  * class initialization:
  *
  * |[
@@ -2415,7 +2415,7 @@ g_object_get_property (GObject	   *object,
  * 						   NULL),
  * 				     "signal::event", gtk_menu_window_event, menu,
  * 				     "signal::size_request", gtk_menu_window_size_request, menu,
- * 				     "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
+ * 				     "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
  * 				     NULL);
  * ]|
  *
@@ -2793,7 +2793,7 @@ g_object_ref_sink (gpointer _object)
  * This function is intended for #GObject implementations to re-enforce a
  * <link linkend="floating-ref">floating</link> object reference.
  * Doing this is seldom required: all
- * #GInitiallyUnowned<!-- -->s are created with a floating reference which
+ * #GInitiallyUnowneds are created with a floating reference which
  * usually just needs to be sunken by calling g_object_ref_sink().
  *
  * Since: 2.10
@@ -4067,9 +4067,9 @@ g_initially_unowned_class_init (GInitiallyUnownedClass *klass)
  * objects.
  *
  * If the object's #GObjectClass.dispose method results in additional
- * references to the object being held, any #GWeakRef<!-- -->s taken
+ * references to the object being held, any #GWeakRefs taken
  * before it was disposed will continue to point to %NULL.  If
- * #GWeakRef<!-- -->s are taken after the object is disposed and
+ * #GWeakRefs are taken after the object is disposed and
  * re-referenced, they will continue to point to it until its refcount
  * goes back to zero, at which point they too will be invalidated.
  */

gobject/gparam.c

@@ -410,7 +410,7 @@ is_canonical (const gchar *key)
  * efficient and in fact required when using property names as detail
  * strings for signals.
  *
- * Beyond the name, #GParamSpec<!-- -->s have two more descriptive
+ * Beyond the name, #GParamSpecs have two more descriptive
  * strings associated with them, the @nick, which should be suitable
  * for use as a label for the property in a property editor, and the
  * @blurb, which should be a somewhat longer description, suitable for
@@ -857,7 +857,7 @@ value_param_lcopy_value (const GValue *value,
 /**
  * GParamSpecPool:
  *
- * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be
+ * A #GParamSpecPool maintains a collection of #GParamSpecs which can be
  * quickly accessed by owner and name. The implementation of the #GObject property
  * system uses such a pool to store the #GParamSpecs of the properties all object
  * types.
@@ -1135,12 +1135,12 @@ pool_list (gpointer key,
  * @pool: a #GParamSpecPool
  * @owner_type: the owner to look for
  *
- * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
+ * Gets an #GList of all #GParamSpecs owned by @owner_type in
  * the pool.
  *
  * Returns: (transfer container) (element-type GObject.ParamSpec): a
- *          #GList of all #GParamSpec<!-- -->s owned by @owner_type in
+ *          #GList of all #GParamSpecs owned by @owner_type in
- *          the pool#GParamSpec<!-- -->s.
+ *          the pool#GParamSpecs.
  */
 GList*
 g_param_spec_pool_list_owned (GParamSpecPool *pool,
@@ -1277,7 +1277,7 @@ pool_depth_list_for_interface (gpointer key,
  * @owner_type: the owner to look for
  * @n_pspecs_p: (out): return location for the length of the returned array
  *
- * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
+ * Gets an array of all #GParamSpecs owned by @owner_type in
  * the pool.
  *
  * Returns: (array length=n_pspecs_p) (transfer container): a newly

gobject/gvalue.c

@@ -56,7 +56,7 @@
  * features.
  *
  * |[
- * #include <glib-object.h>
+ * #include <glib-object.h>
  *
  * static void
  * int2string (const GValue *src_value,
@@ -78,34 +78,34 @@
  *   const gchar *message;
  *
  *   /&ast; The GValue starts empty &ast;/
- *   g_assert (!G_VALUE_HOLDS_STRING (&amp;a));
+ *   g_assert (!G_VALUE_HOLDS_STRING (&a));
  *
  *   /&ast; Put a string in it &ast;/
- *   g_value_init (&amp;a, G_TYPE_STRING);
+ *   g_value_init (&a, G_TYPE_STRING);
- *   g_assert (G_VALUE_HOLDS_STRING (&amp;a));
+ *   g_assert (G_VALUE_HOLDS_STRING (&a));
- *   g_value_set_static_string (&amp;a, "Hello, world!");
+ *   g_value_set_static_string (&a, "Hello, world!");
- *   g_printf ("%s\n", g_value_get_string (&amp;a));
+ *   g_printf ("%s\n", g_value_get_string (&a));
  *
  *   /&ast; Reset it to its pristine state &ast;/
- *   g_value_unset (&amp;a);
+ *   g_value_unset (&a);
  *
  *   /&ast; It can then be reused for another type &ast;/
- *   g_value_init (&amp;a, G_TYPE_INT);
+ *   g_value_init (&a, G_TYPE_INT);
- *   g_value_set_int (&amp;a, 42);
+ *   g_value_set_int (&a, 42);
  *
  *   /&ast; Attempt to transform it into a GValue of type STRING &ast;/
- *   g_value_init (&amp;b, G_TYPE_STRING);
+ *   g_value_init (&b, G_TYPE_STRING);
  *
  *   /&ast; An INT is transformable to a STRING &ast;/
  *   g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
  *
- *   g_value_transform (&amp;a, &amp;b);
+ *   g_value_transform (&a, &b);
- *   g_printf ("%s\n", g_value_get_string (&amp;b));
+ *   g_printf ("%s\n", g_value_get_string (&b));
  *
  *   /&ast; Attempt to transform it again using a custom transform function &ast;/
  *   g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
- *   g_value_transform (&amp;a, &amp;b);
+ *   g_value_transform (&a, &b);
- *   g_printf ("%s\n", g_value_get_string (&amp;b));
+ *   g_printf ("%s\n", g_value_get_string (&b));
  *   return 0;
  * }
  * ]|