GNOME.org
 

[glib] docs: Ditch more markup

commit 49cc207e35ef6b6ce7f4954a4c067ab43145f6bf
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Mar 2 18:20:37 2014 -0500

    docs: Ditch more markup
    
    Some markup was hiding in docs in headers. Drop it there, too.

 gio/gdbusconnection.h |   48 +++++++--------
 gio/gioenums.h        |   15 ++---
 gio/gsettings.h       |    2 +-
 gio/gvolume.h         |   13 ++---
 glib/gbacktrace.h     |    2 +-
 glib/gmarkup.h        |    4 +-
 glib/goption.h        |  157 +++++++++++++++++++++----------------------------
 glib/gspawn.h         |   91 ++++++++++++++---------------
 gobject/gsignal.h     |    5 +-
 gobject/gtype.h       |    6 +-
 gobject/gtypeplugin.h |    8 +--
 gobject/gvalue.h      |    7 +-
 12 files changed, 160 insertions(+), 198 deletions(-)
---
diff --git a/gio/gdbusconnection.h b/gio/gdbusconnection.h
index 8f200ba..ffded9e 100644
--- a/gio/gdbusconnection.h
+++ b/gio/gdbusconnection.h
@@ -340,36 +340,32 @@ typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *conne
  *
  * Since 2.38, if you want to handle getting/setting D-Bus properties
  * asynchronously, give %NULL as your get_property() or set_property()
- * function.  The D-Bus call will be directed to your @method_call
- * function, with the provided @interface_name set to
- * <literal>"org.freedesktop.DBus.Properties"</literal>.
- *
- * The usual checks on the validity of the calls is performed.  For
- * <literal>'Get'</literal> calls, an error is automatically returned if
- * the property does not exist or the permissions do not allow access.
- * The same checks are performed for <literal>'Set'</literal> calls, and
- * the provided value is also checked for being the correct type.
- *
- * For both <literal>'Get'</literal> and <literal>'Set'</literal> calls,
- * the #GDBusMethodInvocation passed to the method_call handler can be
- * queried with g_dbus_method_invocation_get_property_info() to get a
- * pointer to the #GDBusPropertyInfo of the property.
- *
- * If you have readable properties specified in your interface info, you
- * must ensure that you either provide a non-%NULL @get_property()
- * function or provide implementations of both the
- * <literal>'Get'</literal> and <literal>'GetAll'</literal> methods on
- * the <literal>'org.freedesktop.DBus.Properties'</literal> interface in
- * your @method_call function.  Note that the required return type of
- * the <literal>'Get'</literal> call is <literal>(v)</literal>, not the
- * type of the property.  <literal>'GetAll'</literal> expects a return
- * value of type <literal>a{sv}</literal>.
- *
- * If you have writable properties specified in your interface info, you
- * must ensure that you either provide a non-%NULL @set_property()
- * function or provide an implementation of the <literal>'Set'</literal>
- * call.  If implementing the call, you must return the value of type
- * %G_VARIANT_TYPE_UNIT.
+ * function. The D-Bus call will be directed to your @method_call function,
+ * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
+ *
+ * The usual checks on the validity of the calls is performed. For
+ * `Get` calls, an error is automatically returned if the property does
+ * not exist or the permissions do not allow access. The same checks are
+ * performed for `Set` calls, and the provided value is also checked for
+ * being the correct type.
+ *
+ * For both `Get` and `Set` calls, the #GDBusMethodInvocation
+ * passed to the @method_call handler can be queried with
+ * g_dbus_method_invocation_get_property_info() to get a pointer
+ * to the #GDBusPropertyInfo of the property.
+ *
+ * If you have readable properties specified in your interface info,
+ * you must ensure that you either provide a non-%NULL @get_property()
+ * function or provide implementations of both the `Get` and `GetAll`
+ * methods on org.freedesktop.DBus.Properties interface in your @method_call
+ * function. Note that the required return type of the `Get` call is
+ * `(v)`, not the type of the property. `GetAll` expects a return value
+ * of type `a{sv}`.
+ *
+ * If you have writable properties specified in your interface info,
+ * you must ensure that you either provide a non-%NULL @set_property()
+ * function or provide an implementation of the `Set` call. If implementing
+ * the call, you must return the value of type %G_VARIANT_TYPE_UNIT.
  *
  * Since: 2.26
  */
diff --git a/gio/gioenums.h b/gio/gioenums.h
index 03f3de9..b934e21 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -218,9 +218,9 @@ typedef enum {
  * @G_FILE_MEASURE_APPARENT_SIZE: Tally usage based on apparent file
  *   sizes.  Normally, the block-size is used, if available, as this is a
  *   more accurate representation of disk space used.
- *   Compare with '<literal>du --apparent-size</literal>'.
+ *   Compare with `du --apparent-size`.
  * @G_FILE_MEASURE_NO_XDEV: Do not cross mount point boundaries.
- *   Compare with '<literal>du -x</literal>'.
+ *   Compare with `du -x`.
  *
  * Flags that can be used with g_file_measure_disk_usage().
  *
@@ -867,12 +867,11 @@ typedef enum {
  * or a socket created with socketpair()).
  *
  * For abstract sockets, there are two incompatible ways of naming
- * them; the man pages suggest using the entire <literal>struct
- * sockaddr_un</literal> as the name, padding the unused parts of the
- * %sun_path field with zeroes; this corresponds to
- * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs
- * instead just use a portion of %sun_path, and pass an appropriate
- * smaller length to bind() or connect(). This is
+ * them; the man pages suggest using the entire `struct sockaddr_un`
+ * as the name, padding the unused parts of the %sun_path field with
+ * zeroes; this corresponds to %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED.
+ * However, many programs instead just use a portion of %sun_path, and
+ * pass an appropriate smaller length to bind() or connect(). This is
  * %G_UNIX_SOCKET_ADDRESS_ABSTRACT.
  *
  * Since: 2.26
diff --git a/gio/gsettings.h b/gio/gsettings.h
index 3025667..02a0337 100644
--- a/gio/gsettings.h
+++ b/gio/gsettings.h
@@ -264,7 +264,7 @@ typedef gboolean      (*GSettingsGetMapping)                            (GVarian
 
 /**
  * GSettingsBindFlags:
- * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
+ * @G_SETTINGS_BIND_DEFAULT: Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET`
  * @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes.
  *     It is an error to use this flag if the property is not writable.
  * @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes.
diff --git a/gio/gvolume.h b/gio/gvolume.h
index c5e13c3..48359e0 100644
--- a/gio/gvolume.h
+++ b/gio/gvolume.h
@@ -68,18 +68,15 @@ G_BEGIN_DECLS
 /**
  * G_VOLUME_IDENTIFIER_KIND_CLASS:
  *
- * The string used to obtain the volume <emphasis>class</emphasis>
- * with g_volume_get_identifier().
+ * The string used to obtain the volume class with g_volume_get_identifier().
  *
- * Known volume classes include <literal>device</literal> and
- * <literal>network</literal>. Other classes may be added in the
- * future.
+ * Known volume classes include `device` and `network`. Other classes may
+ * be added in the future.
  *
  * This is intended to be used by applications to classify #GVolume
  * instances into different sections - for example a file manager or
- * file chooser can use this information to show
- * <literal>network</literal> volumes under a "Network" heading and
- * <literal>device</literal> volumes under a "Devices" heading.
+ * file chooser can use this information to show `network` volumes under
+ * a "Network" heading and `device` volumes under a "Devices" heading.
  */
 #define G_VOLUME_IDENTIFIER_KIND_CLASS "class"
 
diff --git a/glib/gbacktrace.h b/glib/gbacktrace.h
index 76ed832..03b6029 100644
--- a/glib/gbacktrace.h
+++ b/glib/gbacktrace.h
@@ -45,7 +45,7 @@ void g_on_error_stack_trace (const gchar *prg_name);
  * Inserts a breakpoint instruction into the code.
  *
  * On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
+ * and on other architectures it raises a `SIGTRAP` signal.
  */
 #if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
 #  define G_BREAKPOINT()        G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
diff --git a/glib/gmarkup.h b/glib/gmarkup.h
index c7efea5..71ff6aa 100644
--- a/glib/gmarkup.h
+++ b/glib/gmarkup.h
@@ -79,7 +79,7 @@ GQuark g_markup_error_quark (void);
  * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked
  *     sections are not passed literally to the @passthrough function of
  *     the parser. Instead, the content of the section (without the
- *     <literal>&lt;![CDATA[</literal> and <literal>]]&gt;</literal>) is
+ *     `<![CDATA[` and `]]>`) is
  *     passed to the @text function. This flag was added in GLib 2.12
  * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup
  *     itself have line/column information prefixed to them to let the
@@ -119,7 +119,7 @@ typedef struct _GMarkupParser GMarkupParser;
  *     is seen.
  * @end_element: Callback to invoke when the closing tag of an element
  *     is seen. Note that this is also called for empty tags like
- *     <literal>&lt;empty/&gt;</literal>.
+ *     `<empty/>`.
  * @text: Callback to invoke when some text is seen (text is always
  *     inside an element). Note that the text of an element may be spread
  *     over multiple calls of this function. If the
diff --git a/glib/goption.h b/glib/goption.h
index 3162dd2..98085a2 100644
--- a/glib/goption.h
+++ b/glib/goption.h
@@ -53,28 +53,28 @@ typedef struct _GOptionEntry   GOptionEntry;
 
 /**
  * GOptionFlags:
- * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
- *  output.
+ * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in `--help` output.
  * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
- *  <option>--help</option> output, even if it is defined in a group.
- * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag
- *  indicates that the sense of the option is reversed.
+ *     `--help` output, even if it is defined in a group.
+ * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this
+ *     flag indicates that the sense of the option is reversed.
  * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind,
- *  this flag indicates that the callback does not take any argument
- *  (like a %G_OPTION_ARG_NONE option). Since 2.8
+ *     this flag indicates that the callback does not take any argument
+ *     (like a %G_OPTION_ARG_NONE option). Since 2.8
  * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK
- *  kind, this flag indicates that the argument should be passed to the
- *  callback in the GLib filename encoding rather than UTF-8. Since 2.8
+ *     kind, this flag indicates that the argument should be passed to the
+ *     callback in the GLib filename encoding rather than UTF-8. Since 2.8
  * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK 
- *  kind, this flag indicates that the argument supply is optional. If no argument
- *  is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
- * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution
- *  which prefixes long option names with <literal>groupname-</literal> if 
- *  there is a conflict. This option should only be used in situations where
- *  aliasing is necessary to model some legacy commandline interface. It is
- *  not safe to use this option, unless all option groups are under your 
- *  direct control. Since 2.8.
- * 
+ *     kind, this flag indicates that the argument supply is optional.
+ *     If no argument is given then data of %GOptionParseFunc will be
+ *     set to NULL. Since 2.8
+ * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict
+ *     resolution which prefixes long option names with `groupname-` if 
+ *     there is a conflict. This option should only be used in situations
+ *     where aliasing is necessary to model some legacy commandline interface.
+ *     It is not safe to use this option, unless all option groups are under
+ *     your direct control. Since 2.8.
+ *
  * Flags which modify individual options.
  */
 typedef enum
@@ -94,24 +94,24 @@ typedef enum
  * @G_OPTION_ARG_STRING: The option takes a string argument.
  * @G_OPTION_ARG_INT: The option takes an integer argument.
  * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
- *  extra argument.
+ *     extra argument.
  * @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
  * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
- *  uses of the option are collected into an array of strings.
+ *     uses of the option are collected into an array of strings.
  * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, 
- *  multiple uses of the option are collected into an array of strings.
+ *     multiple uses of the option are collected into an array of strings.
  * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument
- *  can be formatted either for the user's locale or for the "C" locale. Since 2.12
- * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT
- *  but for larger numbers. The number can be in decimal base, or in hexadecimal
- *  (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>).
- *  Since 2.12
+ *     can be formatted either for the user's locale or for the "C" locale.
+ *     Since 2.12
+ * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like
+ *     %G_OPTION_ARG_INT but for larger numbers. The number can be in
+ *     decimal base, or in hexadecimal (when prefixed with `0x`, for
+ *     example, `0xffffffff`). Since 2.12
  * 
  * The #GOptionArg enum values determine which type of extra argument the
- * options expect to find. If an option expects an extra argument, it
- * can be specified in several ways; with a short option:
- * <option>-x arg</option>, with a long option: <option>--name arg</option>
- * or combined in a single argument: <option>--name=arg</option>.
+ * options expect to find. If an option expects an extra argument, it can
+ * be specified in several ways; with a short option: `-x arg`, with a long
+ * option: `--name arg` or combined in a single argument: `--name=arg`.
  */
 typedef enum
 {
@@ -213,67 +213,44 @@ GQuark g_option_error_quark (void);
 /**
  * GOptionEntry:
  * @long_name: The long name of an option can be used to specify it
- *  in a commandline as --<replaceable>long_name</replaceable>. Every
- *  option must have a long name. To resolve conflicts if multiple
- *  option groups contain the same long name, it is also possible to
- *  specify the option as 
- *  --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
+ *     in a commandline as `--long_name`. Every option must have a
+ *     long name. To resolve conflicts if multiple option groups contain
+ *     the same long name, it is also possible to specify the option as 
+ *     `--groupname-long_name`.
  * @short_name: If an option has a short name, it can be specified
- *  -<replaceable>short_name</replaceable> in a commandline. @short_name must be 
- *  a printable ASCII character different from '-', or zero if the option has no
- *  short name.
- * @flags: Flags from #GOptionFlags.
- * @arg: The type of the option, as a #GOptionArg.
- * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must 
- *  point to a #GOptionArgFunc callback function, which will be called to handle 
- *  the extra argument. Otherwise, @arg_data is a pointer to a location to store 
- *  the value, the required type of the location depends on the @arg type:
- *  <variablelist>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_NONE</term>
- *  <listitem><para>%gboolean</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_STRING</term>
- *  <listitem><para>%gchar*</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_INT</term>
- *  <listitem><para>%gint</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_FILENAME</term>
- *  <listitem><para>%gchar*</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_STRING_ARRAY</term>
- *  <listitem><para>%gchar**</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_FILENAME_ARRAY</term>
- *  <listitem><para>%gchar**</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_DOUBLE</term>
- *  <listitem><para>%gdouble</para></listitem>
- *  </varlistentry>
- *  </variablelist>
- *  If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location
- *  will contain a newly allocated string if the option was given. That string
- *  needs to be freed by the callee using g_free(). Likewise if @arg type is
- *  %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should
- *  be freed using g_strfreev().
- * @description: the description for the option in <option>--help</option>
- *  output. The @description is translated using the @translate_func of the
- *  group, see g_option_group_set_translation_domain().
+ *     `-short_name` in a commandline. @short_name must be  a printable
+ *     ASCII character different from '-', or zero if the option has no
+ *     short name.
+ * @flags: Flags from #GOptionFlags
+ * @arg: The type of the option, as a #GOptionArg
+ * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data
+ *     must point to a #GOptionArgFunc callback function, which will be
+ *     called to handle the extra argument. Otherwise, @arg_data is a
+ *     pointer to a location to store the value, the required type of
+ *     the location depends on the @arg type:
+ *     - %G_OPTION_ARG_NONE: %gboolean
+ *     - %G_OPTION_ARG_STRING: %gchar*
+ *     - %G_OPTION_ARG_INT: %gint
+ *     - %G_OPTION_ARG_FILENAME: %gchar*
+ *     - %G_OPTION_ARG_STRING_ARRAY: %gchar**
+ *     - %G_OPTION_ARG_FILENAME_ARRAY: %gchar**
+ *     - %G_OPTION_ARG_DOUBLE: %gdouble
+ *     If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME,
+ *     the location will contain a newly allocated string if the option
+ *     was given. That string needs to be freed by the callee using g_free().
+ *     Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or
+ *     %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().
+ * @description: the description for the option in `--help`
+ *     output. The @description is translated using the @translate_func
+ *     of the group, see g_option_group_set_translation_domain().
  * @arg_description: The placeholder to use for the extra argument parsed
- *  by the option in <option>--help</option>
- *  output. The @arg_description is translated using the @translate_func of the
- *  group, see g_option_group_set_translation_domain().
+ *     by the option in `--help` output. The @arg_description is translated
+ *     using the @translate_func of the group, see
+ *     g_option_group_set_translation_domain().
  * 
- * A <structname>GOptionEntry</structname> defines a single option.
- * To have an effect, they must be added to a #GOptionGroup with
- * g_option_context_add_main_entries() or g_option_group_add_entries().
+ * A GOptionEntry struct defines a single option. To have an effect, they
+ * must be added to a #GOptionGroup with g_option_context_add_main_entries()
+ * or g_option_group_add_entries().
  */
 struct _GOptionEntry
 {
@@ -293,12 +270,12 @@ struct _GOptionEntry
  * 
  * If a long option in the main group has this name, it is not treated as a 
  * regular option. Instead it collects all non-option arguments which would
- * otherwise be left in <literal>argv</literal>. The option must be of type
+ * otherwise be left in `argv`. The option must be of type
  * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
  * or %G_OPTION_ARG_FILENAME_ARRAY.
  * 
  * 
- * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
+ * Using #G_OPTION_REMAINING instead of simply scanning `argv`
  * for leftover arguments has the advantage that GOption takes care of 
  * necessary encoding conversions for strings or filenames.
  * 
diff --git a/glib/gspawn.h b/glib/gspawn.h
index 7a993e9..eb7304b 100644
--- a/glib/gspawn.h
+++ b/glib/gspawn.h
@@ -45,25 +45,25 @@ G_BEGIN_DECLS
  * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
  * @G_SPAWN_ERROR_READ: Read or select on pipes failed.
  * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
- * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
- * @G_SPAWN_ERROR_TOO_BIG: execv() returned <literal>E2BIG</literal>
+ * @G_SPAWN_ERROR_ACCES: execv() returned `EACCES`
+ * @G_SPAWN_ERROR_PERM: execv() returned `EPERM`
+ * @G_SPAWN_ERROR_TOO_BIG: execv() returned `E2BIG`
  * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG
- * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
- * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
- * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
- * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
- * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
- * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
- * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
- * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
- * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
- * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
- * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned `ENOEXEC`
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned `ENAMETOOLONG`
+ * @G_SPAWN_ERROR_NOENT: execv() returned `ENOENT`
+ * @G_SPAWN_ERROR_NOMEM: execv() returned `ENOMEM`
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned `ENOTDIR`
+ * @G_SPAWN_ERROR_LOOP: execv() returned `ELOOP`
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned `ETXTBUSY`
+ * @G_SPAWN_ERROR_IO: execv() returned `EIO`
+ * @G_SPAWN_ERROR_NFILE: execv() returned `ENFILE`
+ * @G_SPAWN_ERROR_MFILE: execv() returned `EMFILE`
+ * @G_SPAWN_ERROR_INVAL: execv() returned `EINVAL`
+ * @G_SPAWN_ERROR_ISDIR: execv() returned `EISDIR`
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned `ELIBBAD`
  * @G_SPAWN_ERROR_FAILED: Some other fatal failure,
- *   <literal>error-&gt;message</literal> should explain.
+ *   `error->message` should explain.
  *
  * Error codes returned by spawning processes.
  */
@@ -124,51 +124,48 @@ typedef enum
  * functions.
  *
  * However, even on POSIX, you are extremely limited in what you can
- * safely do from a #GSpawnChildSetupFunc, because any mutexes that
- * were held by other threads in the parent process at the time of the
- * fork() will still be locked in the child process, and they will
- * never be unlocked (since the threads that held them don't exist in
- * the child). POSIX allows only async-signal-safe functions (see
- * <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
- * to be called in the child between fork() and exec(), which
- * drastically limits the usefulness of child setup functions.
+ * safely do from a #GSpawnChildSetupFunc, because any mutexes that were
+ * held by other threads in the parent process at the time of the fork()
+ * will still be locked in the child process, and they will never be
+ * unlocked (since the threads that held them don't exist in the child).
+ * POSIX allows only async-signal-safe functions (see signal(7)) to be
+ * called in the child between fork() and exec(), which drastically limits
+ * the usefulness of child setup functions.
  *
  * In particular, it is not safe to call any function which may
  * call malloc(), which includes POSIX functions such as setenv().
  * If you need to set up the child environment differently from
  * the parent, you should use g_get_environ(), g_environ_setenv(),
  * and g_environ_unsetenv(), and then pass the complete environment
- * list to the <literal>g_spawn...</literal> function.
+ * list to the `g_spawn...` function.
  */
 typedef void (* GSpawnChildSetupFunc) (gpointer user_data);
 
 /**
  * GSpawnFlags:
  * @G_SPAWN_DEFAULT: no flags, default behaviour
- * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
- *   inherited by the child; otherwise all descriptors except stdin/stdout/stderr
- *   will be closed before calling exec() in the child.
- * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
- *   must use g_child_watch_add() yourself (or call waitpid()
- *   or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
- * @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
- *   it will be looked for in the user's <envar>PATH</envar>.
+ * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will
+ *     be inherited by the child; otherwise all descriptors except stdin,
+ *     stdout and stderr will be closed before calling exec() in the child.
+ * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped;
+ *     you must use g_child_watch_add() yourself (or call waitpid() or handle
+ *     `SIGCHLD` yourself), or the child will become a zombie.
+ * @G_SPAWN_SEARCH_PATH: `argv[0]` need not be an absolute path, it will be
+ *     looked for in the user's `PATH`.
  * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded,
- *   instead of going to the same location as the parent's standard output.
+ *     instead of going to the same location as the parent's standard output.
  * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
  * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard
- *   input (by default, the child's standard input is attached to
- *   <filename>/dev/null</filename>).
- * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is
- *   the file to execute, while the remaining elements are the actual argument
- *   vector to pass to the file. Normally g_spawn_async_with_pipes() uses
- *   <literal>argv[0]</literal> as the file to execute, and passes all of
- *   <literal>argv</literal> to the child.
- * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if <literal>argv[0]</literal> is not an abolute path,
- *   it will be looked for in the <envar>PATH</envar> from the passed child 
- *   environment. Since: 2.34
- * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the O_CLOEXEC flag set.
- *   Since: 2.40.
+ *     input (by default, the child's standard input is attached to `/dev/null`).
+ * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of `argv` is the file to
+ *     execute, while the remaining elements are the actual argument vector
+ *     to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]`
+ *     as the file to execute, and passes all of `argv` to the child.
+ * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if `argv[0]` is not an abolute path,
+ *     it will be looked for in the `PATH` from the passed child environment.
+ *     Since: 2.34
+ * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the `O_CLOEXEC` flag set.
+ *     Since: 2.40
  *
  * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
  */
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index c8e64b6..9e3acf8 100644
--- a/gobject/gsignal.h
+++ b/gobject/gsignal.h
@@ -192,9 +192,8 @@ typedef enum
  * assume that instances thereof remain persistent across all signal emissions
  * they are used in. This is only useful for non ref-counted, value-copy types.
  * 
- * To flag a signal argument in this way, add 
- * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
- * of g_signal_new().
+ * To flag a signal argument in this way, add `| G_SIGNAL_TYPE_STATIC_SCOPE`
+ * to the corresponding argument of g_signal_new().
  * |[
  * g_signal_new ("size_request",
  *   G_TYPE_FROM_CLASS (gobject_class),
diff --git a/gobject/gtype.h b/gobject/gtype.h
index 802877f..a1c2d90 100644
--- a/gobject/gtype.h
+++ b/gobject/gtype.h
@@ -57,7 +57,7 @@ G_BEGIN_DECLS
  * G_TYPE_NONE:
  * 
  * A fundamental type which is used as a replacement for the C
- * <literal>void</literal> return type.
+ * void return type.
  */
 #define G_TYPE_NONE                    G_TYPE_MAKE_FUNDAMENTAL (1)
 /**
@@ -1476,8 +1476,8 @@ guint     g_type_get_type_registration_serial (void);
  * function.
  *
  * The macro expects the interface initialization function to have the
- * name <literal>t_n ## _default_init</literal>, and the interface
- * structure to have the name <literal>TN ## Interface</literal>.
+ * name `t_n ## _default_init`, and the interface structure to have the
+ * name `TN ## Interface`.
  *
  * Since: 2.24
  */
diff --git a/gobject/gtypeplugin.h b/gobject/gtypeplugin.h
index afb2d2b..43748ea 100644
--- a/gobject/gtypeplugin.h
+++ b/gobject/gtypeplugin.h
@@ -91,12 +91,10 @@ typedef void  (*GTypePluginCompleteInterfaceInfo) (GTypePlugin     *plugin,
  * @unuse_plugin: Decreases the use count of the plugin.
  * @complete_type_info: Fills in the #GTypeInfo and 
  *  #GTypeValueTable structs for the type. The structs are initialized
- *  with <literal>memset(s, 0, sizeof (s))</literal> before calling 
- *  this function.
+ *  with `memset(s, 0, sizeof (s))` before calling this function.
  * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo 
- *  for the interface. The structs is initialized with 
- *  <literal>memset(s, 0, sizeof (s))</literal> before calling
- *  this function.
+ *  for the interface. The structs is initialized with
+ *  `memset(s, 0, sizeof (s))` before calling this function.
  * 
  * The #GTypePlugin interface is used by the type system in order to handle
  * the lifecycle of dynamically loaded types.
diff --git a/gobject/gvalue.h b/gobject/gvalue.h
index 5ff485f..9f9bfaf 100644
--- a/gobject/gvalue.h
+++ b/gobject/gvalue.h
@@ -173,10 +173,9 @@ void       g_value_register_transform_func (GType           src_type,
 /**
  * G_VALUE_INIT:
  *
- * A #GValue must be initialized before it can be used.
- * This macro can be used as initializer instead of an explicit
- * <literal>{ 0 }</literal> when declaring a variable,
- * but it cannot be assigned to a variable.
+ * A #GValue must be initialized before it can be used. This macro can
+ * be used as initializer instead of an explicit `{ 0 }` when declaring
+ * a variable, but it cannot be assigned to a variable.
  *
  * |[
  *   GValue value = G_VALUE_INIT;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]