diff --git a/glib/gasyncqueue.c b/glib/gasyncqueue.c index db053f399..98c7d8a60 100644 --- a/glib/gasyncqueue.c +++ b/glib/gasyncqueue.c @@ -88,9 +88,9 @@ /** * GAsyncQueue: * - * The GAsyncQueue struct is an opaque data structure which represents - * an asynchronous queue. It should only be accessed through the - * g_async_queue_* functions. + * An opaque data structure which represents an asynchronous queue. + * + * It should only be accessed through the `g_async_queue_*` functions. */ struct _GAsyncQueue { diff --git a/glib/gbookmarkfile.h b/glib/gbookmarkfile.h index e9cfbf12b..82ea98d5d 100644 --- a/glib/gbookmarkfile.h +++ b/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 - * private data and should not be directly accessed. + * An opaque data structure representing a set of bookmarks. */ typedef struct _GBookmarkFile GBookmarkFile; diff --git a/glib/gchecksum.h b/glib/gchecksum.h index 599f439c1..5bb52d824 100644 --- a/glib/gchecksum.h +++ b/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(). * diff --git a/glib/gdataset.c b/glib/gdataset.c index bfff3e009..793e21f8b 100644 --- a/glib/gdataset.c +++ b/glib/gdataset.c @@ -121,9 +121,9 @@ /** * GData: * - * The #GData struct is an opaque data structure to represent a - * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be - * accessed via the following functions. + * An opaque data structure that represents a keyed data list. + * + * See also: [Keyed data lists][glib-Keyed-Data-Lists]. **/ /** diff --git a/glib/gdatetime.h b/glib/gdatetime.h index fa43d8531..4e1afdf9b 100644 --- a/glib/gdatetime.h +++ b/glib/gdatetime.h @@ -89,8 +89,7 @@ typedef gint64 GTimeSpan; /** * GDateTime: * - * `GDateTime` is an opaque structure whose members - * cannot be accessed directly. + * An opaque structure that represents a date and time, including a time zone. * * Since: 2.26 */ diff --git a/glib/gfileutils.c b/glib/gfileutils.c index e0a2a65d0..2a0db4f97 100644 --- a/glib/gfileutils.c +++ b/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) diff --git a/glib/gfileutils.h b/glib/gfileutils.h index d6b1d9eec..4c9633224 100644 --- a/glib/gfileutils.h +++ b/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 - * 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 - * over the old. + * 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()` + * on the file and use of an atomic `rename()` of the new version of the file + * 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 - * 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 - * directory containing the file after calling `rename()`. + * 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 + * the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the + * 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 - * 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. + * 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 + * 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. diff --git a/glib/gmessages.h b/glib/gmessages.h index 43c6d67b9..f0b3a8685 100644 --- a/glib/gmessages.h +++ b/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, diff --git a/glib/gshell.c b/glib/gshell.c index afdc04671..33c53497a 100644 --- a/glib/gshell.c +++ b/glib/gshell.c @@ -48,9 +48,11 @@ /** * G_SHELL_ERROR: * - * Error domain for shell functions. Errors in this domain will be from - * the #GShellError enumeration. See #GError for information on error - * domains. + * Error domain for shell functions. + * + * 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 - * the shell, for example, you should first 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 + * quoted string to mean @unquoted_string. + * + * If you pass a filename to the shell, for example, you should first + * 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 - * quotes; if a string contains file globs, arithmetic operators, - * variables, backticks, redirections, or other special-to-the-shell - * features, the result will be different from the result a real shell - * would produce (the variables, backticks, etc. will be passed - * through literally instead of being expanded). This function is - * guaranteed to succeed if applied to the result of + * Unquotes a string as the shell (/bin/sh) would. + * + * This function only handles quotes; if a string contains file globs, + * arithmetic operators, variables, backticks, redirections, or other + * special-to-the-shell features, the result will be different from the + * result a real shell would produce (the variables, backticks, etc. + * 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 - * escaped text; g_shell_unquote() simply goes through the string and - * unquotes/unescapes anything that the shell would. Both single and - * double quotes are 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. + * error. + * + * The @quoted_string need not actually contain quoted or escaped text; + * g_shell_unquote() simply goes through the string and unquotes/unescapes + * anything that the shell would. Both single and double quotes are + * 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 - * like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to - * be escaped with backslash. Otherwise double quotes preserve things - * literally. + * `\'` - if you want a `'` in the quoted text, you have to do something + * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and + * newline to be escaped with backslash. Otherwise double quotes + * 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 - * those you would get from a UNIX98 /bin/sh, as long as the input - * contains none of the unsupported shell expansions. If the input - * does contain such expansions, they are passed through - * literally. Possible errors are those from the #G_SHELL_ERROR - * domain. Free the returned vector with g_strfreev(). + * etc. are not supported). + * + * The results are defined to be the same as those you would get from + * a UNIX98 `/bin/sh`, as long as the input contains none of the + * unsupported shell expansions. If the input does contain such expansions, + * 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 **/ diff --git a/glib/gslice.c b/glib/gslice.c index d6335c9dd..690d21e07 100644 --- a/glib/gslice.c +++ b/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*), - * though in general slices are 2 * sizeof (void*) bytes aligned, - * if a malloc() fallback implementation is used instead, - * the alignment may be reduced in a libc dependent fashion. + * to at least `1 * sizeof (void*)`, though in general slices + * are `2 * sizeof (void*)` bytes aligned; if a `malloc()` + * fallback implementation is used instead, the alignment may + * 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 - * only if @mem_size is 0 + * Returns: a pointer to the allocated memory block, which will + * be %NULL if and only if @mem_size is 0 * * Since: 2.10 */ diff --git a/glib/gspawn.c b/glib/gspawn.c index 3f432a576..ac8449d65 100644 --- a/glib/gspawn.c +++ b/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 - * 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. + * block waiting for the child to exit). * - * 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 + * The child program is 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 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 - * main(). wmain() has a wide character argument vector as parameter. + * tools it is enough to make the program have a `wmain()` instead of + * `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(). - * That is, @child_setup is called just before calling exec() in the + * pipes, closing file descriptors, etc.) but before calling `exec()`. + * 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 - * GetExitCodeProcess(). You should close the handle with CloseHandle() + * with the `WaitFor*()` functions, or examine its exit code with + * `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 - * 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 - * 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 + * removed, taking a command line instead of an argument vector. + * + * See g_spawn_sync() for full details. + * + * The @command_line argument will be parsed by g_shell_parse_argv(). + * + * 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 - * command line in the background. Unlike g_spawn_async(), the + * g_shell_parse_argv() and passes it to g_spawn_async(). + * + * 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 */ diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index b6ff60f51..ef6920643 100644 --- a/glib/gstrfuncs.c +++ b/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 - * allow nesting such as + * and returns @string itself, not a copy. + * + * The return value is to allow nesting such as: + * * |[ * 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(): + * * |[ * 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, - * and return @string itself, not a copy. The return value is to allow - * nesting such as + * replaces the character with @substitutor. + * + * Modifies @string in place, and return @string itself, not a copy. The + * return value is to allow nesting such as: + * * |[ * 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(): + * * |[ * reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); * ... * g_free (reformatted); * ]| * - * Returns: @string + * Returns: the modified @string */ gchar * g_strcanon (gchar *string, diff --git a/glib/gunicode.h b/glib/gunicode.h index d72980380..496e4dec8 100644 --- a/glib/gunicode.h +++ b/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 - * 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 - * character. The macro returns the start of the next UTF-8 character. + * Skips to the next character in a UTF-8 string. + * + * The string must be 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 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. */