documentation fixes

Fixes for gtk-doc warnings.

http://bugzilla.gnome.org/show_bug.cgi?id=66469

https://bugzilla.gnome.org/show_bug.cgi?id=664699

docs/reference/glib/glib-sections.txt

@@ -1853,6 +1853,7 @@ G_KEY_FILE_DESKTOP_TYPE_DIRECTORY
 
 <SUBSECTION Private>
 g_key_file_error_quark
+g_key_file_get_type
 </SECTION>
 
 <SECTION>
@@ -2416,6 +2417,9 @@ g_bytes_ref
 g_bytes_unref
 g_bytes_unref_to_data
 g_bytes_unref_to_array
+
+<SUBSECTION Private>
+g_bytes_get_type
 </SECTION>
 
 <SECTION>

docs/reference/gobject/gobject-sections.txt

@@ -506,6 +506,8 @@ GParamSpecChar
 g_param_spec_char
 g_value_set_char
 g_value_get_char
+g_value_get_schar
+g_value_set_schar
 
 <SUBSECTION guchar>
 G_IS_PARAM_SPEC_UCHAR

glib/docs.c

@@ -1456,6 +1456,7 @@
 
 /**
  * GFloatIEEE754:
+ * @v_float: the double value
  *
  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
  * mantissa and exponent of IEEE floats and doubles. These unions are defined
@@ -1465,6 +1466,7 @@
 
 /**
  * GDoubleIEEE754:
+ * @v_double: the double value
  *
  * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
  * mantissa and exponent of IEEE floats and doubles. These unions are defined
@@ -1694,7 +1696,7 @@
 /**
  * G_CONST_RETURN:
  *
- * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
+ * If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands
  * to nothing. By default, the macro expands to <literal>const</literal>.
  * The macro should be used in place of <literal>const</literal> for
  * functions that return a value that should not be modified. The
@@ -1735,7 +1737,7 @@
  *
  * This macro is used to export function prototypes so they can be linked
  * with an external version when no inlining is performed. The file which
- * implements the functions should define %G_IMPLEMENTS_INLINES
+ * implements the functions should define <literal>G_IMPLEMENTS_INLINES</literal>
  * before including the headers which contain %G_INLINE_FUNC declarations.
  * Since inlining is very compiler-dependent using these macros correctly
  * is very difficult. Their use is strongly discouraged.

glib/garray.c

@@ -619,8 +619,8 @@ g_array_remove_range (GArray *farray,
  * greater than second arg).
  *
  * If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order – i.e.
+ * is undefined. If you want equal elements to keep their order (i.e.
- * you want a stable sort – you can write a comparison function that,
+ * you want a stable sort) you can write a comparison function that,
  * if two elements would otherwise compare equal, compares them by
  * their addresses.
  **/
@@ -1272,8 +1272,8 @@ g_ptr_array_add (GPtrArray *farray,
  * greater than second arg).
  *
  * If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order – i.e.
+ * is undefined. If you want equal elements to keep their order (i.e.
- * you want a stable sort – you can write a comparison function that,
+ * you want a stable sort) you can write a comparison function that,
  * if two elements would otherwise compare equal, compares them by
  * their addresses.
  *
@@ -1656,8 +1656,8 @@ g_byte_array_remove_range (GByteArray *array,
  * first arg is greater than second arg).
  *
  * If two array elements compare equal, their order in the sorted array
- * is undefined. If you want equal elements to keep their order – i.e.
+ * is undefined. If you want equal elements to keep their order (i.e.
- * you want a stable sort – you can write a comparison function that,
+ * you want a stable sort) you can write a comparison function that,
  * if two elements would otherwise compare equal, compares them by
  * their addresses.
  **/

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 %SIGTRAP signal.
+ * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
  */
 #if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
 #  define G_BREAKPOINT()        G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END

glib/gerror.c

@@ -281,7 +281,7 @@
  *   If there's a "generic" or "unknown" error code for unrecoverable
  *   errors it doesn't make sense to distinguish with specific codes,
  *   it should be called <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</literal>,
- *   for example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
+ *   for example %G_SPAWN_ERROR_FAILED.
  * </para></listitem>
  * </itemizedlist>
  *

glib/gfileutils.c

@@ -109,7 +109,7 @@
  *     not correctly attached to the computer.
  * @G_FILE_ERROR_NODEV: The underlying file system of the specified file
  *     does not support memory mapping.
- * G_FILE_ERROR_ROFS: The directory containing the new link can't be
+ * @G_FILE_ERROR_ROFS: The directory containing the new link can't be
  *     modified because it's on a read-only file system.
  * @G_FILE_ERROR_TXTBSY: Text file busy.
  * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory.
@@ -310,7 +310,7 @@ g_mkdir_with_parents (const gchar *pathname,
  * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
  * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
  * its name indicates that it is executable, checking for well-known
- * extensions and those listed in the %PATHEXT environment variable.
+ * extensions and those listed in the <envar>PATHEXT</envar> environment variable.
  *
  * Return value: whether a test was %TRUE
  **/
@@ -469,9 +469,9 @@ g_file_error_quark (void)
  * g_file_error_from_errno:
  * @err_no: an "errno" value
  * 
- * Gets a #GFileError constant based on the passed-in @errno.
+ * Gets a #GFileError constant based on the passed-in @err_no.
- * For example, if you pass in %EEXIST this function returns
+ * For example, if you pass in <literal>EEXIST</literal> this function returns
- * #G_FILE_ERROR_EXIST. Unlike @errno values, you can portably
+ * #G_FILE_ERROR_EXIST. Unlike <literal>errno</literal> values, you can portably
  * assume that all #GFileError values will exist.
  *
  * Normally a #GFileError value goes into a #GError returned

glib/ggettext.c

@@ -407,7 +407,7 @@ g_dgettext (const gchar *domain,
  * @category: a locale category
  *
  * This is a variant of g_dgettext() that allows specifying a locale
- * category instead of always using %LC_MESSAGES. See g_dgettext() for
+ * category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for
  * more information about how this functions differs from calling
  * dcgettext() directly.
  *

glib/ghook.c

@@ -77,7 +77,7 @@
  * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed
  * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run
  * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for
- *   hook flags; see #G_HOOK_FLAGS_USER_SHIFT
+ *   hook flags; see %G_HOOK_FLAG_USER_SHIFT
  *
  * Flags used internally in the #GHook implementation.
  */
@@ -86,7 +86,7 @@
  * G_HOOK_FLAGS:
  * @hook: a #GHook
  *
- * Returns the flags of a hook.
+ * Gets the flags of a hook.
  */
 
 /**

glib/giochannel.c

@@ -752,7 +752,7 @@ g_io_channel_get_buffer_condition (GIOChannel *channel)
 
 /**
  * g_io_channel_error_from_errno:
- * @en: an <literal>errno</literal> error number, e.g. %EINVAL
+ * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal>
  *
  * Converts an <literal>errno</literal> error number to a #GIOChannelError.
  *
@@ -937,18 +937,18 @@ g_io_channel_get_line_term (GIOChannel *channel,
  * @flags: the flags to set on the IO channel
  * @error: A location to return an error of type #GIOChannelError
  *
- * Sets the (writeable) flags in @channel to (@flags & %G_IO_CHANNEL_SET_MASK).
+ * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).
  *
  * Return value: the status of the operation. 
  **/
 /**
  * GIOFlags:
- * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
+ * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal>
  *                    (see the documentation of the UNIX open()
  *                    syscall).
  * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
- *                      %O_NONBLOCK/%O_NDELAY (see the documentation of
+ *                      <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal>
- *                      the UNIX open() syscall).
+ *                      (see the documentation of the UNIX open() syscall).
  * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
  *                         This flag cannot be changed.
  * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.

glib/glib-init.c

@@ -34,7 +34,7 @@
  * g_mem_gc_friendly:
  *
  * This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
- * includes the key <link linkend="G_DEBUG">gc-friendly</link>.
+ * includes the key <literal>gc-friendly</literal>.
  */
 #ifdef ENABLE_GC_FRIENDLY_DEFAULT
 gboolean g_mem_gc_friendly = TRUE;

glib/glib-unix.c

@@ -70,12 +70,13 @@ g_unix_set_error_from_errno (GError **error,
  * Similar to the UNIX pipe() call, but on modern systems like Linux
  * uses the pipe2() system call, which atomically creates a pipe with
  * the configured flags.  The only supported flag currently is
- * %FD_CLOEXEC.  If for example you want to configure %O_NONBLOCK,
+ * <literal>FD_CLOEXEC</literal>.  If for example you want to configure
- * that must still be done separately with fcntl().
+ * <literal>O_NONBLOCK</literal>, that must still be done separately with
+ * fcntl().
  *
- * <note>This function does *not* take %O_CLOEXEC, it takes
+ * <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
- * %FD_CLOEXEC as if for fcntl(); these are different on
+ * <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
- * Linux/glibc.</note>
+ * different on Linux/glibc.</note>
  *
  * Returns: %TRUE on success, %FALSE if not (and errno will be set).
  *
@@ -134,8 +135,8 @@ g_unix_open_pipe (int     *fds,
  * @error: a #GError
  *
  * Control the non-blocking state of the given file descriptor,
- * according to @nonblock.  On most systems this uses %O_NONBLOCK, but
+ * according to @nonblock.  On most systems this uses <literal>O_NONBLOCK</literal>, but
- * on some older ones may use %O_NDELAY.
+ * on some older ones may use <literal>O_NDELAY</literal>.
  *
  * Returns: %TRUE if successful
  *
@@ -184,12 +185,13 @@ g_unix_set_fd_nonblocking (gint       fd,
  * @signum: A signal number
  *
  * Create a #GSource that will be dispatched upon delivery of the UNIX
- * signal @signum.  Currently only %SIGHUP, %SIGINT, and %SIGTERM can
+ * signal @signum.  Currently only <literal>SIGHUP</literal>,
+ * <literal>SIGINT</literal>, and <literal>SIGTERM</literal> can
  * be monitored.  Note that unlike the UNIX default, all sources which
  * have created a watch will be dispatched, regardless of which
  * underlying thread invoked g_unix_signal_source_new().
  *
- * For example, an effective use of this function is to handle SIGTERM
+ * For example, an effective use of this function is to handle <literal>SIGTERM</literal>
  * cleanly; flushing any outstanding files, and then calling
  * g_main_loop_quit ().  It is not safe to do any of this a regular
  * UNIX signal handler; your handler may be invoked while malloc() or

glib/glib-unix.h

@@ -52,8 +52,8 @@ G_BEGIN_DECLS
  * It is expected that most code will not look at %errno from these
  * APIs. Important cases where one would want to differentiate between
  * errors are already covered by existing cross-platform GLib API,
- * such as e.g. #GFile wrapping %ENOENT.  However, it is provided for
+ * such as e.g. #GFile wrapping <literal>ENOENT</literal>.  However, it is
- * completeness, at least.
+ * provided for completeness, at least.
  */
 #define G_UNIX_ERROR (g_unix_error_quark())
 

glib/gmain.c

@@ -1995,13 +1995,13 @@ g_clock_win32_init (void)
  *
  * Queries the system monotonic time, if available.
  *
- * On POSIX systems with clock_gettime() and %CLOCK_MONOTONIC this call
+ * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call
  * is a very shallow wrapper for that.  Otherwise, we make a best effort
  * that probably involves returning the wall clock time (with at least
  * microsecond accuracy, subject to the limitations of the OS kernel).
  *
- * It's important to note that POSIX %CLOCK_MONOTONIC does not count
+ * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does
- * time spent while the machine is suspended.
+ * not count time spent while the machine is suspended.
  *
  * On Windows, "limitations of the OS kernel" is a rather substantial
  * statement.  Depending on the configuration of the system, the wall

glib/gmain.h

@@ -88,8 +88,6 @@ typedef struct _GSourceCallbackFuncs    GSourceCallbackFuncs;
  *     callback function with @user_data and whatever additional parameters
  *     are needed for this type of event source.
  * @finalize: Called when the source is finalized.
- * @closure_callback:
- * @closure_marshal:
  *
  * The <structname>GSourceFuncs</structname> struct contains a table of
  * functions used to handle event sources in a generic manner.
@@ -200,6 +198,7 @@ struct _GSourceFuncs
                         gpointer    user_data);
   void     (*finalize) (GSource    *source); /* Can be NULL */
 
+  /*< private >*/
   /* For use by g_source_set_closure */
   GSourceFunc     closure_callback;        
   GSourceDummyMarshal closure_marshal; /* Really is of type GClosureMarshal */

glib/gmessages.c

@@ -165,7 +165,7 @@
  * A convenience function/macro to log a warning message.
  *
  * You can make warnings fatal at runtime by setting the
- * %G_DEBUG environment variable (see
+ * <envar>G_DEBUG</envar> environment variable (see
  * <ulink url="glib-running.html">Running GLib Applications</ulink>).
  */
 
@@ -182,7 +182,7 @@
  * example.
  *
  * You can also make critical warnings fatal at runtime by
- * setting the %G_DEBUG environment variable (see
+ * setting the <envar>G_DEBUG</envar> environment variable (see
  * <ulink url="glib-running.html">Running GLib Applications</ulink>).
  */
 
@@ -379,7 +379,7 @@ g_log_domain_get_handler_L (GLogDomain	*domain,
  * %G_LOG_LEVEL_ERROR is always fatal.
  *
  * You can also make some message levels fatal at runtime by setting
- * the %G_DEBUG environment variable (see
+ * the <envar>G_DEBUG</envar> environment variable (see
  * <ulink url="glib-running.html">Running GLib Applications</ulink>).
  *
  * Returns: the old fatal mask

glib/gpoll.h

@@ -86,6 +86,9 @@ typedef gint    (*GPollFunc)    (GPollFD *ufds,
  *     for writing you would use %G_IO_OUT | %G_IO_ERR.
  * @revents: a bitwise combination of flags from #GIOCondition, returned
  *     from the poll() function to indicate which events occurred.
+ *
+ * Represents a file descriptor, which events to poll for, and which events
+ * occurred.
  */
 struct _GPollFD
 {

glib/gscanner.c

@@ -113,6 +113,20 @@
  * @G_TOKEN_LEFT_PAREN: a '(' character
  * @G_TOKEN_LEFT_CURLY: a '{' character
  * @G_TOKEN_RIGHT_CURLY: a '}' character
+ * @G_TOKEN_RIGHT_PAREN: a ')' character
+ * @G_TOKEN_ERROR: an error occurred
+ * @G_TOKEN_CHAR: a character
+ * @G_TOKEN_BINARY: a binary integer
+ * @G_TOKEN_OCTAL: an octal integer
+ * @G_TOKEN_INT: an integer
+ * @G_TOKEN_HEX: a hex integer
+ * @G_TOKEN_FLOAT: a floating point number
+ * @G_TOKEN_STRING: a string
+ * @G_TOKEN_SYMBOL: a symbol
+ * @G_TOKEN_IDENTIFIER: an identifier
+ * @G_TOKEN_IDENTIFIER_NULL: a null identifier
+ * @G_TOKEN_COMMENT_SINGLE: one line comment
+ * @G_TOKEN_COMMENT_MULTI: multi line comment
  *
  * The possible types of token returned from each
  * g_scanner_get_next_token() call.
@@ -120,6 +134,18 @@
 
 /**
  * GTokenValue:
+ * @v_symbol: token symbol value
+ * @v_identifier: token identifier value
+ * @v_binary: token binary integer value
+ * @v_octal: octal integer value
+ * @v_int: integer value
+ * @v_int64: 64-bit integer value
+ * @v_float: floating point value
+ * @v_hex: hex integer value
+ * @v_string: string value
+ * @v_comment: comment value
+ * @v_char: character value
+ * @v_error: error value
  *
  * A union holding the value of the token.
  */
@@ -136,17 +162,17 @@
  * @G_ERR_FLOAT_MALFORMED: malformed floating point number
  *
  * The possible errors, used in the @v_error field
- * of #GTokenValue, when the token is a #G_TOKEN_ERROR.
+ * of #GTokenValue, when the token is a %G_TOKEN_ERROR.
  */
 
 /**
  * GScanner:
- * @user_data:
+ * @user_data: unused
- * @max_parse_errors:
+ * @max_parse_errors: unused
- * @parse_errors:
+ * @parse_errors: g_scanner_error() increments this field
- * @input_name:
+ * @input_name: name of input stream, featured by the default message handler
- * @qdata:
+ * @qdata: quarked data
- * @config:
+ * @config: link into the scanner configuration
  * @token: token parsed by the last g_scanner_get_next_token()
  * @value: value of the last token from g_scanner_get_next_token()
  * @line: line number of the last token from g_scanner_get_next_token()
@@ -155,12 +181,7 @@
  * @next_value: value of the last token from g_scanner_peek_next_token()
  * @next_line: line number of the last token from g_scanner_peek_next_token()
  * @next_position: char number of the last token from g_scanner_peek_next_token()
- * @symbol_table:
+ * @msg_handler: handler function for _warn and _error
- * @input_fd:
- * @text:
- * @text_end:
- * @buffer:
- * @scope_id:
  *
  * The data structure representing a lexical scanner.
  *
@@ -206,7 +227,7 @@
  * @scan_identifier_1char: specifies if single-character
  *     identifiers are recognized (the default is %FALSE).
  * @scan_identifier_NULL: specifies if %NULL is reported as
- *     #G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
+ *     %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).
  * @scan_symbols: specifies if symbols are recognized (the default
  *     is %TRUE).
  * @scan_binary: specifies if binary numbers are recognized (the
@@ -225,19 +246,19 @@
  *     quotes (the default is %TRUE).
  * @numbers_2_int: specifies if binary, octal and hexadecimal numbers
  *     are reported as #G_TOKEN_INT (the default is %TRUE).
- * @int_2_float: specifies if all numbers are reported as #G_TOKEN_FLOAT
+ * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT
  *     (the default is %FALSE).
  * @identifier_2_string: specifies if identifiers are reported as strings
  *     (the default is %FALSE).
  * @char_2_token: specifies if characters are reported by setting
- *     <literal>token = ch</literal> or as #G_TOKEN_CHAR (the default
+ *     <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default
  *     is %TRUE).
  * @symbol_2_token: specifies if symbols are reported by setting
- *     <literal>token = v_symbol</literal> or as #G_TOKEN_SYMBOL (the
+ *     <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the
  *     default is %FALSE).
  * @scope_0_fallback: specifies if a symbol is searched for in the
  *     default scope in addition to the current scope (the default is %FALSE).
- * @store_int64:
+ * @store_int64: use value.v_int64 rather than v_int
  *
  * Specifies the #GScanner parser configuration. Most settings can
  * be changed during the parsing phase and will affect the lexical
@@ -1269,12 +1290,12 @@ g_scanner_get_char (GScanner	*scanner,
  * @expected_token: the expected token
  * @identifier_spec: a string describing how the scanner's user
  *     refers to identifiers (%NULL defaults to "identifier").
- *     This is used if @expected_token is #G_TOKEN_IDENTIFIER or
+ *     This is used if @expected_token is %G_TOKEN_IDENTIFIER or
- *     #G_TOKEN_IDENTIFIER_NULL.
+ *     %G_TOKEN_IDENTIFIER_NULL.
  * @symbol_spec: a string describing how the scanner's user refers
  *     to symbols (%NULL defaults to "symbol"). This is used if
- *     @expected_token is #G_TOKEN_SYMBOL or any token value greater
+ *     @expected_token is %G_TOKEN_SYMBOL or any token value greater
- *     than #G_TOKEN_LAST.
+ *     than %G_TOKEN_LAST.
  * @symbol_name: the name of the symbol, if the scanner's current
  *     token is a symbol.
  * @message: a message string to output at the end of the

glib/gscanner.h

@@ -105,6 +105,8 @@ typedef enum
   
   G_TOKEN_COMMENT_SINGLE,
   G_TOKEN_COMMENT_MULTI,
+
+  /*< private >*/
   G_TOKEN_LAST
 } GTokenType;
 
@@ -161,6 +163,8 @@ struct	_GScannerConfig
   guint		symbol_2_token : 1;
   guint		scope_0_fallback : 1;		/* try scope 0 on lookups? */
   guint		store_int64 : 1; 		/* use value.v_int64 rather than v_int */
+
+  /*< private >*/
   guint		padding_dummy;
 };
 
@@ -193,7 +197,8 @@ struct	_GScanner
   GTokenValue		next_value;
   guint			next_line;
   guint			next_position;
-  
+
+  /*< private >*/
   /* to be considered private */
   GHashTable		*symbol_table;
   gint			input_fd;
@@ -201,7 +206,8 @@ struct	_GScanner
   const gchar		*text_end;
   gchar			*buffer;
   guint			scope_id;
-  
+
+  /*< public >*/
   /* handler function for _warn and _error */
   GScannerMsgFunc	msg_handler;
 };

glib/gspawn.c

@@ -112,7 +112,7 @@ g_spawn_error_quark (void)
  * <note><para>
  * If you are writing a GTK+ application, and the program you 
  * are spawning is a graphical application, too, then you may
- * want to use gdk_spawn_on_screen() instead to ensure that 
+ * want to use gdk_spawn_on_screen() instead to ensure that
  * the spawned program opens its windows on the right screen.
  * </para></note>
  *
@@ -484,7 +484,7 @@ g_spawn_sync (const gchar          *working_directory,
  * will only be searched if you pass the %G_SPAWN_SEARCH_PATH flag.
  * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
  * used, then the program will be run from the current directory (or
- * %working_directory, if specified); this might be unexpected or even
+ * @working_directory, if specified); this might be unexpected or even
  * dangerous in some cases when the current directory is world-writable.
  *
  * On Windows, note that all the string or string vector arguments to
@@ -538,7 +538,7 @@ g_spawn_sync (const gchar          *working_directory,
  * call g_spawn_close_pid() on the @child_pid, in order to free
  * resources which may be associated with the child process. (On Unix,
  * using a child watch is equivalent to calling waitpid() or handling
- * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
+ * the <literal>SIGCHLD</literal> signal manually. On Windows, calling g_spawn_close_pid()
  * is equivalent to calling CloseHandle() on the process handle returned
  * in @child_pid).  See g_child_watch_add().
  *
@@ -622,7 +622,7 @@ g_spawn_sync (const gchar          *working_directory,
  * <note><para>
  * If you are writing a GTK+ application, and the program you 
  * are spawning is a graphical application, too, then you may
- * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that 
+ * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
  * the spawned program opens its windows on the right screen.
  * </para></note>
  * 

glib/gspawn.h

@@ -45,22 +45,22 @@ 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 %EACCES.
+ * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
- * @G_SPAWN_ERROR_PERM: execv() returned %EPERM.
+ * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
- * @G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
+ * @G_SPAWN_ERROR_2BIG: execv() returned <literal>E2BIG</literal>
- * @G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
- * @G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
+ * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
- * @G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
+ * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
- * @G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
- * @G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
+ * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
- * @G_SPAWN_ERROR_IO: execv() returned %EIO.
+ * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
- * @G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
+ * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
- * @G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
+ * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
- * @G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
+ * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
- * @G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
+ * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
- * @G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
  * @G_SPAWN_ERROR_FAILED: Some other fatal failure,
  *   <literal>error-&gt;message</literal> should explain.
  *
@@ -125,7 +125,7 @@ typedef enum
  * 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_unsetev(), and then pass the complete environment
+ * and g_environ_unsetenv(), and then pass the complete environment
  * list to the <literal>g_spawn...</literal> function.
  */
 typedef void (* GSpawnChildSetupFunc) (gpointer user_data);

glib/gstdio.c

@@ -744,7 +744,7 @@ g_fopen (const gchar *filename,
  * 
  * See your C library manual for more details about freopen().
  *
- * Returns: A <type>FILE</type> pointer if the file was successfully
+ * Returns: A <literal>FILE</literal> pointer if the file was successfully
  *    opened, or %NULL if an error occurred.
  * 
  * Since: 2.6

glib/gstrfuncs.c

@@ -100,7 +100,7 @@
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
  * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII alphanumeric character
@@ -116,7 +116,7 @@
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
  * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII alphabetic character
@@ -132,7 +132,7 @@
  * recognizes standard ASCII control characters and ignores the
  * locale, returning %FALSE for all non-ASCII characters. Also,
  * unlike the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
  * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII control character.
@@ -146,7 +146,7 @@
  *
  * Unlike the standard C library isdigit() function, this takes
  * a <type>char</type>, not an <type>int</type>, so don't call it
- * on %EOF, but no need to cast to #guchar before passing a possibly
+ * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
  * non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII digit.
@@ -162,7 +162,7 @@
  * recognizes standard ASCII characters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
  * to cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII printing character other than space.
@@ -178,7 +178,7 @@
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
  * to worry about casting to #guchar before passing a possibly
  * non-ASCII character in.
  *
@@ -195,7 +195,7 @@
  * recognizes standard ASCII characters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
  * to cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII printing character.
@@ -211,7 +211,7 @@
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
  * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII punctuation character.
@@ -227,7 +227,7 @@
  * recognizes standard ASCII white-space and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
  * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII white-space character
@@ -243,7 +243,7 @@
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
  * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on %EOF, but no need to
+ * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
  * worry about casting to #guchar before passing a possibly non-ASCII
  * character in.
  *
@@ -258,7 +258,7 @@
  *
  * Unlike the standard C library isxdigit() function, this takes
  * a <type>char</type>, not an <type>int</type>, so don't call it
- * on %EOF, but no need to cast to #guchar before passing a
+ * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
  * possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
@@ -669,12 +669,12 @@ g_strtod (const gchar *nptr,
  * To convert from a #gdouble to a string in a locale-insensitive
  * way, use g_ascii_dtostr().
  *
- * If the correct value would cause overflow, plus or minus %HUGE_VAL
+ * If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
- * is returned (according to the sign of the value), and %ERANGE is
+ * is returned (according to the sign of the value), and <literal>ERANGE</literal> is
- * stored in %errno. If the correct value would cause underflow,
+ * stored in <literal>errno</literal>. If the correct value would cause underflow,
- * zero is returned and %ERANGE is stored in %errno.
+ * zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
  *
- * This function resets %errno before calling strtod() so that
+ * This function resets <literal>errno</literal> before calling strtod() so that
  * you can reliably detect overflow and underflow.
  *
  * Return value: the #gdouble value.
@@ -1121,10 +1121,11 @@ g_parse_long_long (const gchar  *nptr,
  * locale-sensitive system strtoull() function.
  *
  * If the correct value would cause overflow, %G_MAXUINT64
- * is returned, and %ERANGE is stored in %errno.  If the base is
+ * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
- * outside the valid range, zero is returned, and %EINVAL is stored
+ * If the base is outside the valid range, zero is returned, and
- * in %errno.  If the string conversion fails, zero is returned, and
+ * <literal>EINVAL</literal> is stored in <literal>errno</literal>.
- * @endptr returns @nptr (if @endptr is non-%NULL).
+ * If the string conversion fails, zero is returned, and @endptr returns
+ * @nptr (if @endptr is non-%NULL).
  *
  * Return value: the #guint64 value or zero on error.
  *
@@ -1167,10 +1168,11 @@ g_ascii_strtoull (const gchar *nptr,
  * locale-sensitive system strtoll() function.
  *
  * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
- * is returned, and %ERANGE is stored in %errno.  If the base is
+ * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
- * outside the valid range, zero is returned, and %EINVAL is stored
+ * If the base is outside the valid range, zero is returned, and
- * in %errno.  If the string conversion fails, zero is returned, and
+ * <literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
- * @endptr returns @nptr (if @endptr is non-%NULL).
+ * string conversion fails, zero is returned, and @endptr returns @nptr
+ * (if @endptr is non-%NULL).
  *
  * Return value: the #gint64 value or zero on error.
  *
@@ -1612,7 +1614,7 @@ g_strreverse (gchar *string)
  * all non-ASCII characters unchanged, even if they are lower case
  * letters in a particular character set. Also unlike the standard
  * library function, this takes and returns a char, not an int, so
- * don't call it on %EOF but no need to worry about casting to #guchar
+ * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
  * before passing a possibly non-ASCII character in.
  *
  * Return value: the result of converting @c to lower case.
@@ -1636,7 +1638,7 @@ g_ascii_tolower (gchar c)
  * all non-ASCII characters unchanged, even if they are upper case
  * letters in a particular character set. Also unlike the standard
  * library function, this takes and returns a char, not an int, so
- * don't call it on %EOF but no need to worry about casting to #guchar
+ * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
  * before passing a possibly non-ASCII character in.
  *
  * Return value: the result of converting @c to upper case.

glib/gtestutils.c

@@ -260,7 +260,7 @@
  * an error message is logged and the application is terminated.
  *
  * The macro can be turned off in final releases of code by defining
- * #G_DISABLE_ASSERT when compiling the application.
+ * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
  */
 
 /**
@@ -271,7 +271,7 @@
  * application is terminated.
  *
  * The macro can be turned off in final releases of code by defining
- * #G_DISABLE_ASSERT when compiling the application.
+ * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
  */
 
 /**
@@ -1281,10 +1281,10 @@ g_test_run (void)
  * Create a new #GTestCase, named @test_name, this API is fairly
  * low level, calling g_test_add() or g_test_add_func() is preferable.
  * When this test is executed, a fixture structure of size @data_size
- * will be allocated and filled with 0s. Then data_setup() is called
+ * will be allocated and filled with 0s. Then @data_setup is called
  * to initialize the fixture. After fixture setup, the actual test
- * function data_test() is called. Once the test run completed, the
+ * function @data_test is called. Once the test run completed, the
- * fixture structure is torn down  by calling data_teardown() and
+ * fixture structure is torn down  by calling @data_teardown and
  * after that the memory is released.
  *
  * Splitting up a test run into fixture setup, test function and
@@ -1557,7 +1557,7 @@ g_test_queue_free (gpointer gfree_pointer)
  * @destroy_func:       Destroy callback for teardown phase.
  * @destroy_data:       Destroy callback data.
  *
- * This function enqueus a callback @destroy_func() to be executed
+ * This function enqueus a callback @destroy_func to be executed
  * during the next test case teardown phase. This is most useful
  * to auto destruct allocted test resources at the end of a test run.
  * Resources are released in reverse queue order, that means enqueueing

glib/gthread-posix.c

@@ -388,7 +388,7 @@ g_rec_mutex_lock (GRecMutex *mutex)
 
 /**
  * g_rec_mutex_unlock:
- * @rec_mutex: a #RecGMutex
+ * @rec_mutex: a #GRecMutex
  *
  * Unlocks @rec_mutex. If another thread is blocked in a
  * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked

glib/gthread.c

@@ -97,7 +97,7 @@
  * Note that it is not safe to assume that your program has no threads
  * even if you don't call g_thread_new() yourself. GLib and GIO can
  * and will create threads for their own purposes in some cases, such
- * as when using g_unix_signal_source_new() or when using #GDBus.
+ * as when using g_unix_signal_source_new() or when using GDBus.
  *
  * Originally, UNIX did not have threads, and therefore some traditional
  * UNIX APIs are problematic in threaded programs. Some notable examples
@@ -158,7 +158,7 @@
  * G_LOCK_DEFINE:
  * @name: the name of the lock
  *
- * The %G_LOCK_* macros provide a convenient interface to #GMutex.
+ * The <literal>G_LOCK_*</literal> macros provide a convenient interface to #GMutex.
  * #G_LOCK_DEFINE defines a lock. It can appear in any place where
  * variable definitions may appear in programs, i.e. in the first block
  * of a function or outside of functions. The @name parameter will be
@@ -166,10 +166,10 @@
  * can use names of existing variables as the parameter - e.g. the name
  * of the variable you intend to protect with the lock. Look at our
  * <function>give_me_next_number()</function> example using the
- * %G_LOCK_* macros:
+ * <literal>G_LOCK_*</literal> macros:
  *
  * <example>
- *  <title>Using the %G_LOCK_* convenience macros</title>
+ *  <title>Using the <literal>G_LOCK_*</literal> convenience macros</title>
  *  <programlisting>
  *   G_LOCK_DEFINE (current_number);
  *

gmodule/gmodule.c

@@ -132,6 +132,7 @@
 
 /**
  * GModule:
+ *
  * The #GModule struct is an opaque data structure to represent a
  * <link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded
  * Module</link>. It should only be accessed via the following functions.

gobject/genums.c

@@ -260,7 +260,7 @@ g_flags_register_static (const gchar	   *name,
  *  enumeration values. The array is terminated by a struct with all
  *  members being 0.
  *
- * This function is meant to be called from the complete_type_info()
+ * This function is meant to be called from the <literal>complete_type_info</literal>
  * function of a #GTypePlugin implementation, as in the following
  * example:
  *