1
0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-30 22:03:29 +02:00

doc: Make file utils docblocks render nicely with gi-docgen

Do not use 4-spaces indentation for return and argument descriptions, to
avoid getting rendered as preformatted blocks.

Annotate code examples with their language, for syntax highlighting.

Isolate the first paragraph to give a short description.
This commit is contained in:
Emmanuele Bassi
2023-01-26 14:24:14 +00:00
parent 293b492334
commit 314d62f302

@@ -1989,8 +1989,9 @@ g_build_path_va (const gchar *separator,
* array of strings containing the path elements. * array of strings containing the path elements.
* *
* Behaves exactly like g_build_path(), but takes the path elements * Behaves exactly like g_build_path(), but takes the path elements
* as a string array, instead of varargs. This function is mainly * as a string array, instead of variadic arguments.
* meant for language bindings. *
* This function is mainly meant for language bindings.
* *
* Returns: (type filename) (transfer full): a newly-allocated string that * Returns: (type filename) (transfer full): a newly-allocated string that
* must be freed with g_free(). * must be freed with g_free().
@@ -2015,10 +2016,12 @@ g_build_pathv (const gchar *separator,
* @...: remaining elements in path, terminated by %NULL * @...: remaining elements in path, terminated by %NULL
* *
* Creates a path from a series of elements using @separator as the * Creates a path from a series of elements using @separator as the
* separator between elements. At the boundary between two elements, * separator between elements.
* any trailing occurrences of separator in the first element, or *
* leading occurrences of separator in the second element are removed * At the boundary between two elements, any trailing occurrences of
* and exactly one copy of the separator is inserted. * separator in the first element, or leading occurrences of separator
* in the second element are removed and exactly one copy of the
* separator is inserted.
* *
* Empty elements are ignored. * Empty elements are ignored.
* *
@@ -2279,14 +2282,15 @@ g_build_filename (const gchar *first_element,
* @error: return location for a #GError * @error: return location for a #GError
* *
* Reads the contents of the symbolic link @filename like the POSIX * Reads the contents of the symbolic link @filename like the POSIX
* readlink() function. * `readlink()` function.
* *
* The returned string is in the encoding used * The returned string is in the encoding used for filenames. Use
* for filenames. Use g_filename_to_utf8() to convert it to UTF-8. * g_filename_to_utf8() to convert it to UTF-8.
* *
* The returned string may also be a relative path. Use g_build_filename() to * The returned string may also be a relative path. Use g_build_filename()
* convert it to an absolute path: * to convert it to an absolute path:
* |[ *
* |[<!-- language="C" -->
* g_autoptr(GError) local_error = NULL; * g_autoptr(GError) local_error = NULL;
* g_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error); * g_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error);
* *
@@ -2752,6 +2756,7 @@ g_path_get_dirname (const gchar *file_name)
* *
* Returns: (type filename) (transfer full): a newly allocated string with the * Returns: (type filename) (transfer full): a newly allocated string with the
* canonical file path * canonical file path
*
* Since: 2.58 * Since: 2.58
*/ */
gchar * gchar *