docs: Break gtk-doc stanzas into paragraphs

Keep the first paragraph short, to act as a summary.

glib/gasyncqueue.c

@@ -88,9 +88,9 @@
 /**
  * GAsyncQueue:
  *
- * The GAsyncQueue struct is an opaque data structure which represents
+ * An opaque data structure which represents an asynchronous queue.
- * an asynchronous queue. It should only be accessed through the
+ *
- * g_async_queue_* functions.
+ * It should only be accessed through the `g_async_queue_*` functions.
  */
 struct _GAsyncQueue
 {

glib/gbookmarkfile.h

@@ -33,6 +33,7 @@ G_BEGIN_DECLS
  * G_BOOKMARK_FILE_ERROR:
  *
  * Error domain for bookmark file parsing.
+ *
  * Errors in this domain will be from the #GBookmarkFileError
  * enumeration. See #GError for information on error domains.
  */
@@ -72,8 +73,7 @@ GQuark g_bookmark_file_error_quark (void);
 /**
  * GBookmarkFile:
  *
- * The `GBookmarkFile` structure contains only
+ * An opaque data structure representing a set of bookmarks.
- * private data and should not be directly accessed.
  */
 typedef struct _GBookmarkFile GBookmarkFile;
 

glib/gchecksum.h

@@ -56,6 +56,7 @@ typedef enum {
  * GChecksum:
  *
  * An opaque structure representing a checksumming operation.
+ *
  * To create a new GChecksum, use g_checksum_new(). To free
  * a GChecksum, use g_checksum_free().
  *

glib/gdataset.c

@@ -121,9 +121,9 @@
 /**
  * GData:
  *
- * The #GData struct is an opaque data structure to represent a
+ * An opaque data structure that represents a keyed data list.
- * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be
+ *
- * accessed via the following functions.
+ * See also: [Keyed data lists][glib-Keyed-Data-Lists].
  **/
 
 /**

glib/gdatetime.h

@@ -89,8 +89,7 @@ typedef gint64 GTimeSpan;
 /**
  * GDateTime:
  *
- * `GDateTime` is an opaque structure whose members
+ * An opaque structure that represents a date and time, including a time zone.
- * cannot be accessed directly.
  *
  * Since: 2.26
  */

glib/gfileutils.c

@@ -502,15 +502,16 @@ G_DEFINE_QUARK (g-file-error-quark, g_file_error)
  * @err_no: an "errno" value
  * 
  * Gets a #GFileError constant based on the passed-in @err_no.
+ *
  * For example, if you pass in `EEXIST` this function returns
- * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
+ * %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
  * assume that all #GFileError values will exist.
  *
  * Normally a #GFileError value goes into a #GError returned
  * from a function that manipulates files. So you would use
  * g_file_error_from_errno() when constructing a #GError.
  * 
- * Returns: #GFileError corresponding to the given @errno
+ * Returns: #GFileError corresponding to the given @err_no
  **/
 GFileError
 g_file_error_from_errno (gint err_no)

glib/gfileutils.h

@@ -75,21 +75,21 @@ typedef enum
 /**
  * GFileSetContentsFlags:
  * @G_FILE_SET_CONTENTS_NONE: No guarantees about file consistency or durability.
- *    The most dangerous setting, which is slightly faster than other settings.
+ *   The most dangerous setting, which is slightly faster than other settings.
  * @G_FILE_SET_CONTENTS_CONSISTENT: Guarantee file consistency: after a crash,
- *    either the old version of the file or the new version of the file will be
+ *   either the old version of the file or the new version of the file will be
- *    available, but not a mixture. On Unix systems this equates to an `fsync()`
+ *   available, but not a mixture. On Unix systems this equates to an `fsync()`
- *    on the file and use of an atomic `rename()` of the new version of the file
+ *   on the file and use of an atomic `rename()` of the new version of the file
- *    over the old.
+ *   over the old.
  * @G_FILE_SET_CONTENTS_DURABLE: Guarantee file durability: after a crash, the
- *    new version of the file will be available. On Unix systems this equates to
+ *   new version of the file will be available. On Unix systems this equates to
- *    an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
+ *   an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
- *    the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
+ *   the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
- *    directory containing the file after calling `rename()`.
+ *   directory containing the file after calling `rename()`.
  * @G_FILE_SET_CONTENTS_ONLY_EXISTING: Only apply consistency and durability
- *    guarantees if the file already exists. This may speed up file operations
+ *   guarantees if the file already exists. This may speed up file operations
- *    if the file doesn’t currently exist, but may result in a corrupted version
+ *   if the file doesn’t currently exist, but may result in a corrupted version
- *    of the new file if the system crashes while writing it.
+ *   of the new file if the system crashes while writing it.
  *
  * Flags to pass to g_file_set_contents_full() to affect its safety and
  * performance.

glib/gmessages.h

@@ -188,7 +188,8 @@ struct _GLogField
  * chained and fall back to simpler handlers in case of failure.
  *
  * Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully;
- *    %G_LOG_WRITER_UNHANDLED otherwise
+ *   %G_LOG_WRITER_UNHANDLED otherwise
+ *
  * Since: 2.50
  */
 typedef GLogWriterOutput (*GLogWriterFunc)     (GLogLevelFlags   log_level,

glib/gshell.c

@@ -48,9 +48,11 @@
 /**
  * G_SHELL_ERROR:
  *
- * Error domain for shell functions. Errors in this domain will be from
+ * Error domain for shell functions.
- * the #GShellError enumeration. See #GError for information on error
+ *
- * domains.
+ * Errors in this domain will be from the #GShellError enumeration.
+ *
+ * See #GError for information on error domains.
  **/
 
 /**
@@ -191,13 +193,17 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
  * @unquoted_string: (type filename): a literal string
  * 
  * Quotes a string so that the shell (/bin/sh) will interpret the
- * quoted string to mean @unquoted_string. If you pass a filename to
+ * quoted string to mean @unquoted_string.
- * the shell, for example, you should first quote it with this
+ *
- * function.  The return value must be freed with g_free(). The
+ * If you pass a filename to the shell, for example, you should first
- * quoting style used is undefined (single or double quotes may be
+ * quote it with this function.
+ *
+ * The return value must be freed with g_free().
+ *
+ * The quoting style used is undefined (single or double quotes may be
  * used).
  * 
- * Returns: (type filename): quoted string
+ * Returns: (type filename) (transfer full): quoted string
  **/
 gchar*
 g_shell_quote (const gchar *unquoted_string)
@@ -241,27 +247,33 @@ g_shell_quote (const gchar *unquoted_string)
  * @quoted_string: (type filename): shell-quoted string
  * @error: error return location or NULL
  * 
- * Unquotes a string as the shell (/bin/sh) would. Only handles
+ * Unquotes a string as the shell (/bin/sh) would.
- * quotes; if a string contains file globs, arithmetic operators,
+ *
- * variables, backticks, redirections, or other special-to-the-shell
+ * This function only handles quotes; if a string contains file globs,
- * features, the result will be different from the result a real shell
+ * arithmetic operators, variables, backticks, redirections, or other
- * would produce (the variables, backticks, etc. will be passed
+ * special-to-the-shell features, the result will be different from the
- * through literally instead of being expanded). This function is
+ * result a real shell would produce (the variables, backticks, etc.
- * guaranteed to succeed if applied to the result of
+ * will be passed through literally instead of being expanded).
+ *
+ * This function is guaranteed to succeed if applied to the result of
  * g_shell_quote(). If it fails, it returns %NULL and sets the
- * error. The @quoted_string need not actually contain quoted or
+ * error.
- * escaped text; g_shell_unquote() simply goes through the string and
+ *
- * unquotes/unescapes anything that the shell would. Both single and
+ * The @quoted_string need not actually contain quoted or escaped text;
- * double quotes are handled, as are escapes including escaped
+ * g_shell_unquote() simply goes through the string and unquotes/unescapes
- * newlines. The return value must be freed with g_free(). Possible
+ * anything that the shell would. Both single and double quotes are
- * errors are in the #G_SHELL_ERROR domain.
+ * handled, as are escapes including escaped newlines.
+ *
+ * The return value must be freed with g_free().
+ *
+ * Possible errors are in the %G_SHELL_ERROR domain.
  * 
  * Shell quoting rules are a bit strange. Single quotes preserve the
  * literal string exactly. escape sequences are not allowed; not even
- * \' - if you want a ' in the quoted text, you have to do something
+ * `\'` - if you want a `'` in the quoted text, you have to do something
- * like 'foo'\''bar'.  Double quotes allow $, `, ", \, and newline to
+ * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and
- * be escaped with backslash. Otherwise double quotes preserve things
+ * newline to be escaped with backslash. Otherwise double quotes
- * literally.
+ * preserve things literally.
  *
  * Returns: (type filename): an unquoted string
  **/
@@ -625,12 +637,16 @@ tokenize_command_line (const gchar *command_line,
  * Parses a command line into an argument vector, in much the same way
  * the shell would, but without many of the expansions the shell would
  * perform (variable expansion, globs, operators, filename expansion,
- * etc. are not supported). The results are defined to be the same as
+ * etc. are not supported).
- * those you would get from a UNIX98 /bin/sh, as long as the input
+ *
- * contains none of the unsupported shell expansions. If the input
+ * The results are defined to be the same as those you would get from
- * does contain such expansions, they are passed through
+ * a UNIX98 `/bin/sh`, as long as the input contains none of the
- * literally. Possible errors are those from the #G_SHELL_ERROR
+ * unsupported shell expansions. If the input does contain such expansions,
- * domain. Free the returned vector with g_strfreev().
+ * they are passed through literally.
+ *
+ * Possible errors are those from the %G_SHELL_ERROR domain.
+ *
+ * Free the returned vector with g_strfreev().
  * 
  * Returns: %TRUE on success, %FALSE if error set
  **/

glib/gslice.c

@@ -998,6 +998,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * @next: the field name of the next pointer in @type
  *
  * Frees a linked list of memory blocks of structure type @type.
+ *
  * The memory blocks must be equal-sized, allocated via
  * g_slice_alloc() or g_slice_alloc0() and linked together by
  * a @next pointer (similar to #GSList). The name of the
@@ -1016,17 +1017,19 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
  * @block_size: the number of bytes to allocate
  *
  * Allocates a block of memory from the slice allocator.
+ *
  * The block address handed out can be expected to be aligned
- * to at least 1 * sizeof (void*),
+ * to at least `1 * sizeof (void*)`, though in general slices
- * though in general slices are 2 * sizeof (void*) bytes aligned,
+ * are `2 * sizeof (void*)` bytes aligned; if a `malloc()`
- * if a malloc() fallback implementation is used instead,
+ * fallback implementation is used instead, the alignment may
- * the alignment may be reduced in a libc dependent fashion.
+ * be reduced in a libc dependent fashion.
+ *
  * Note that the underlying slice allocation mechanism can
  * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
- * Returns: a pointer to the allocated memory block, which will be %NULL if and
+ * Returns: a pointer to the allocated memory block, which will
- *    only if @mem_size is 0
+ *   be %NULL if and only if @mem_size is 0
  *
  * Since: 2.10
  */

glib/gspawn.c

@@ -209,6 +209,8 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
  * @user_data: (closure): user data for @child_setup
  * @child_pid: (out) (optional): return location for child process reference, or %NULL
  * @error: return location for error
+ *
+ * Executes a child program asynchronously.
  * 
  * See g_spawn_async_with_pipes() for a full description; this function
  * simply calls the g_spawn_async_with_pipes() without any pipes.
@@ -216,7 +218,7 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
  * You should call g_spawn_close_pid() on the returned child process
  * reference when you don't need it any more.
  * 
- * If you are writing a GTK+ application, and the program you are spawning is a
+ * If you are writing a GTK application, and the program you are spawning is a
  * graphical application too, then to ensure that the spawned program opens its
  * windows on the right screen, you may want to use #GdkAppLaunchContext,
  * #GAppLaunchContext, or set the %DISPLAY environment variable.
@@ -329,6 +331,7 @@ read_data (GString *str,
  * @error: return location for error, or %NULL
  *
  * Executes a child synchronously (waits for the child to exit before returning).
+ *
  * All output from the child is stored in @standard_output and @standard_error,
  * if those parameters are non-%NULL. Note that you must set the  
  * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
@@ -665,52 +668,53 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
  * @error: return location for error
  *
  * Executes a child program asynchronously (your program will not
- * block waiting for the child to exit). The child program is
+ * block waiting for the child to exit).
- * specified by the only argument that must be provided, @argv.
- * @argv should be a %NULL-terminated array of strings, to be passed
- * as the argument vector for the child. The first string in @argv
- * is of course the name of the program to execute. By default, the
- * name of the program must be a full path. If @flags contains the
- * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
- * used to search for the executable. If @flags contains the
- * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
- * @envp is used to search for the executable. If both the
- * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
- * are set, the `PATH` variable from @envp takes precedence over
- * the environment variable.
  *
- * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
+ * The child program is specified by the only argument that must be
- * used, then the program will be run from the current directory (or
+ * provided, @argv. @argv should be a %NULL-terminated array of strings,
- * @working_directory, if specified); this might be unexpected or even
+ * to be passed as the argument vector for the child. The first string
+ * in @argv is of course the name of the program to execute. By default,
+ * the name of the program must be a full path. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to
+ * search for the executable. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp
+ * is used to search for the executable. If both the
+ * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
+ * set, the `PATH` variable from @envp takes precedence over the
+ * environment variable.
+ *
+ * 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
  * dangerous in some cases when the current directory is world-writable.
  *
  * On Windows, note that all the string or string vector arguments to
- * this function and the other g_spawn*() functions are in UTF-8, the
+ * this function and the other `g_spawn*()` functions are in UTF-8, the
  * GLib file name encoding. Unicode characters that are not part of
  * the system codepage passed in these arguments will be correctly
  * available in the spawned program only if it uses wide character API
  * to retrieve its command line. For C programs built with Microsoft's
- * tools it is enough to make the program have a wmain() instead of
+ * tools it is enough to make the program have a `wmain()` instead of
- * main(). wmain() has a wide character argument vector as parameter.
+ * `main()`. `wmain()` has a wide character argument vector as parameter.
  *
- * At least currently, mingw doesn't support wmain(), so if you use
+ * At least currently, mingw doesn't support `wmain()`, so if you use
  * mingw to develop the spawned program, it should call
  * g_win32_get_command_line() to get arguments in UTF-8.
  *
- * On Windows the low-level child process creation API CreateProcess()
+ * On Windows the low-level child process creation API `CreateProcess()`
  * doesn't use argument vectors, but a command line. The C runtime
- * library's spawn*() family of functions (which g_spawn_async_with_pipes()
+ * library's `spawn*()` family of functions (which g_spawn_async_with_pipes()
  * eventually calls) paste the argument vector elements together into
  * a command line, and the C runtime startup code does a corresponding
  * reconstruction of an argument vector from the command line, to be
- * passed to main(). Complications arise when you have argument vector
+ * passed to `main()`. Complications arise when you have argument vector
  * elements that contain spaces or double quotes. The `spawn*()` functions
  * don't do any quoting or escaping, but on the other hand the startup
  * code does do unquoting and unescaping in order to enable receiving
  * arguments with embedded spaces or double quotes. To work around this
  * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
  * argument vector elements that need it before calling the C runtime
- * spawn() function.
+ * `spawn()` function.
  *
  * The returned @child_pid on Windows is a handle to the child
  * process, not its identifier. Process handles and process
@@ -729,13 +733,13 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
  * 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()
- * is equivalent to calling CloseHandle() on the process handle returned
+ * is equivalent to calling `CloseHandle()` on the process handle returned
  * in @child_pid). See g_child_watch_add().
  *
  * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
  * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
  * other open file descriptors will be inherited by the child; otherwise all
- * descriptors except stdin/stdout/stderr will be closed before calling exec()
+ * descriptors except stdin/stdout/stderr will be closed before calling `exec()`
  * in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
  * absolute path, it will be looked for in the `PATH` environment
  * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
@@ -776,25 +780,25 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
  * @child_setup and @user_data are a function and user data. On POSIX
  * platforms, the function is called in the child after GLib has
  * performed all the setup it plans to perform (including creating
- * pipes, closing file descriptors, etc.) but before calling exec().
+ * pipes, closing file descriptors, etc.) but before calling `exec()`.
- * That is, @child_setup is called just before calling exec() in the
+ * That is, @child_setup is called just before calling `exec()` in the
  * child. Obviously actions taken in this function will only affect
  * the child, not the parent.
  *
- * On Windows, there is no separate fork() and exec() functionality.
+ * On Windows, there is no separate `fork()` and `exec()` functionality.
  * Child processes are created and run with a single API call,
- * CreateProcess(). There is no sensible thing @child_setup
+ * `CreateProcess()`. There is no sensible thing @child_setup
  * could be used for on Windows so it is ignored and not called.
  *
  * If non-%NULL, @child_pid will on Unix be filled with the child's
  * process ID. You can use the process ID to send signals to the child,
- * or to use g_child_watch_add() (or waitpid()) if you specified the
+ * or to use g_child_watch_add() (or `waitpid()`) if you specified the
  * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
  * filled with a handle to the child process only if you specified the
  * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
  * process using the Win32 API, for example wait for its termination
- * with the WaitFor*() functions, or examine its exit code with
+ * with the `WaitFor*()` functions, or examine its exit code with
- * GetExitCodeProcess(). You should close the handle with CloseHandle()
+ * `GetExitCodeProcess()`. You should close the handle with `CloseHandle()`
  * or g_spawn_close_pid() when you no longer need it.
  *
  * If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out
@@ -818,7 +822,7 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
  * @error can be %NULL to ignore errors, or non-%NULL to report errors.
  * If an error is set, the function returns %FALSE. Errors are reported
  * even if they occur in the child (for example if the executable in
- * @argv[0] is not found). Typically the `message` field of returned
+ * `@argv[0]` is not found). Typically the `message` field of returned
  * errors should be displayed to users. Possible errors are those from
  * the #G_SPAWN_ERROR domain.
  *
@@ -829,7 +833,7 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
  * process reference must be closed using g_spawn_close_pid().
  *
  * On modern UNIX platforms, GLib can use an efficient process launching
- * codepath driven internally by posix_spawn(). This has the advantage of
+ * codepath driven internally by `posix_spawn()`. This has the advantage of
  * avoiding the fork-time performance costs of cloning the parent process
  * address space, and avoiding associated memory overcommit checks that are
  * not relevant in the context of immediately executing a distinct process.
@@ -841,9 +845,11 @@ g_spawn_async_with_pipes (const gchar          *working_directory,
  * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
  * 4. @working_directory is %NULL
  * 5. @child_setup is %NULL
- * 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
+ * 6. The program is of a recognised binary format, or has a shebang.
+ *    Otherwise, GLib will have to execute the program through the
+ *    shell, which is not done using the optimized codepath.
  *
- * If you are writing a GTK+ application, and the program you are spawning is a
+ * If you are writing a GTK application, and the program you are spawning is a
  * graphical application too, then to ensure that the spawned program opens its
  * windows on the right screen, you may want to use #GdkAppLaunchContext,
  * #GAppLaunchContext, or set the `DISPLAY` environment variable.
@@ -925,6 +931,8 @@ g_spawn_async_with_pipes_and_fds (const gchar           *working_directory,
  * @stderr_fd: file descriptor to use for child's stderr, or `-1`
  * @error: return location for error
  *
+ * Executes a child program asynchronously.
+ *
  * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
  * so no FD assignments are used.
  *
@@ -986,12 +994,17 @@ g_spawn_async_with_fds (const gchar          *working_directory,
  * @error: return location for errors
  *
  * A simple version of g_spawn_sync() with little-used parameters
- * removed, taking a command line instead of an argument vector.  See
+ * removed, taking a command line instead of an argument vector.
- * g_spawn_sync() for full details. @command_line will be parsed by
+ *
- * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
+ * See g_spawn_sync() for full details.
- * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
+ *
- * implications, so consider using g_spawn_sync() directly if
+ * The @command_line argument will be parsed by g_shell_parse_argv().
- * appropriate. Possible errors are those from g_spawn_sync() and those
+ *
+ * Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
+ * Note that %G_SPAWN_SEARCH_PATH can have security implications, so
+ * consider using g_spawn_sync() directly if appropriate.
+ *
+ * Possible errors are those from g_spawn_sync() and those
  * from g_shell_parse_argv().
  *
  * If @wait_status is non-%NULL, the platform-specific status of
@@ -1050,8 +1063,9 @@ g_spawn_command_line_sync (const gchar  *command_line,
  * @error: return location for errors
  * 
  * A simple version of g_spawn_async() that parses a command line with
- * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
+ * g_shell_parse_argv() and passes it to g_spawn_async().
- * command line in the background. Unlike g_spawn_async(), the
+ *
+ * Runs a command line in the background. Unlike g_spawn_async(), the
  * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
  * that %G_SPAWN_SEARCH_PATH can have security implications, so
  * consider using g_spawn_async() directly if appropriate. Possible
@@ -1134,7 +1148,7 @@ g_spawn_command_line_async (const gchar *command_line,
  * functionality, although under a misleading name.
  *
  * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
- *     @error will be set)
+ *   @error will be set)
  *
  * Since: 2.70
  */

glib/gstrfuncs.c

@@ -2028,22 +2028,26 @@ g_strncasecmp (const gchar *s1,
  * @new_delimiter: the new delimiter character
  *
  * Converts any delimiter characters in @string to @new_delimiter.
+ *
  * Any characters in @string which are found in @delimiters are
  * changed to the @new_delimiter character. Modifies @string in place,
- * and returns @string itself, not a copy. The return value is to
+ * and returns @string itself, not a copy.
- * allow nesting such as
+ *
+ * The return value is to allow nesting such as:
+ *
  * |[<!-- language="C" -->
  *   g_ascii_strup (g_strdelimit (str, "abc", '?'))
  * ]|
  *
- * In order to modify a copy, you may use `g_strdup()`:
+ * In order to modify a copy, you may use g_strdup():
+ *
  * |[<!-- language="C" -->
  *   reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
  *   ...
  *   g_free (reformatted);
  * ]|
  *
- * Returns: @string
+ * Returns: the modified @string
  */
 gchar *
 g_strdelimit (gchar       *string,
@@ -2073,21 +2077,24 @@ g_strdelimit (gchar       *string,
  * @substitutor: replacement character for disallowed bytes
  *
  * For each character in @string, if the character is not in @valid_chars,
- * replaces the character with @substitutor. Modifies @string in place,
+ * replaces the character with @substitutor.
- * and return @string itself, not a copy. The return value is to allow
+ *
- * nesting such as
+ * Modifies @string in place, and return @string itself, not a copy. The
+ * return value is to allow nesting such as:
+ *
  * |[<!-- language="C" -->
  *   g_ascii_strup (g_strcanon (str, "abc", '?'))
  * ]|
  *
- * In order to modify a copy, you may use `g_strdup()`:
+ * In order to modify a copy, you may use g_strdup():
+ *
  * |[<!-- language="C" -->
  *   reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
  *   ...
  *   g_free (reformatted);
  * ]|
  *
- * Returns: @string
+ * Returns: the modified @string
  */
 gchar *
 g_strcanon (gchar       *string,

glib/gunicode.h

@@ -758,10 +758,15 @@ GLIB_VAR const gchar * const g_utf8_skip;
  * g_utf8_next_char:
  * @p: Pointer to the start of a valid UTF-8 character
  *
- * Skips to the next character in a UTF-8 string. The string must be
+ * Skips to the next character in a UTF-8 string.
- * valid; this macro is as fast as possible, and has no error-checking.
+ *
- * You would use this macro to iterate over a string character by
+ * The string must be valid; this macro is as fast as possible, and has
- * character. The macro returns the start of the next UTF-8 character.
+ * no error-checking.
+ *
+ * You would use this macro to iterate over a string character by character.
+ *
+ * The macro returns the start of the next UTF-8 character.
+ *
  * Before using this macro, use g_utf8_validate() to validate strings
  * that may contain invalid UTF-8.
  */