luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-04-01 05:13:06 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clarify the path construction functions

Browse Source 
Use the same wording for functions that belong in the same family, and
link to the newly introduced GPathBuf API.
This commit is contained in:
Emmanuele Bassi 2023-01-26 14:25:45 +00:00
parent 314d62f302
commit 280649fb82
1 changed files with 26 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
glib/gfileutils.c
View File

@ -2044,8 +2044,7 @@ g_build_pathv (const gchar *separator,
* copies of the separator, elements consisting only of copies * copies of the separator, elements consisting only of copies
* of the separator are ignored. * of the separator are ignored.
* *
* Returns: (type filename) (transfer full): a newly-allocated string that * Returns: (type filename) (transfer full): the newly allocated path
* must be freed with g_free().
**/ **/
gchar * gchar *
g_build_path (const gchar *separator, g_build_path (const gchar *separator,
@ -2201,11 +2200,16 @@ g_build_filename_va (const gchar *first_argument,
* @first_element: (type filename): the first element in the path * @first_element: (type filename): the first element in the path
* @args: va_list of remaining elements in path * @args: va_list of remaining elements in path
* *
* Behaves exactly like g_build_filename(), but takes the path elements * Creates a filename from a list of elements using the correct
* as a va_list. This function is mainly meant for language bindings. * separator for the current platform.
* *
* Returns: (type filename) (transfer full): a newly-allocated string that * Behaves exactly like g_build_filename(), but takes the path elements
* must be freed with g_free(). * as a va_list.
*
* This function is mainly meant for implementing other variadic arguments
* functions.
*
* Returns: (type filename) (transfer full): the newly allocated path
* *
* Since: 2.56 * Since: 2.56
*/ */
@ -2221,14 +2225,19 @@ g_build_filename_valist (const gchar *first_element,
/** /**
* g_build_filenamev: * g_build_filenamev:
* @args: (array zero-terminated=1) (element-type filename): %NULL-terminated * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
* array of strings containing the path elements. * array of strings containing the path elements.
* *
* Behaves exactly like g_build_filename(), but takes the path elements * Creates a filename from a vector of elements using the correct
* as a string array, instead of varargs. This function is mainly * separator for the current platform.
*
* This function behaves exactly like g_build_filename(), but takes the path
* elements as a string array, instead of varargs. This function is mainly
* meant for language bindings. * meant for language bindings.
* *
* Returns: (type filename) (transfer full): a newly-allocated string that * If you are building a path programmatically you may want to use
* must be freed with g_free(). * #GPathBuf instead.
*
* Returns: (type filename) (transfer full): the newly allocated path
* *
* Since: 2.8 * Since: 2.8
*/ */
@ -2244,7 +2253,7 @@ g_build_filenamev (gchar **args)
* @...: remaining elements in path, terminated by %NULL * @...: remaining elements in path, terminated by %NULL
* *
* Creates a filename from a series of elements using the correct * Creates a filename from a series of elements using the correct
* separator for filenames. * separator for the current platform.
* *
* On Unix, this function behaves identically to `g_build_path * On Unix, this function behaves identically to `g_build_path
* (G_DIR_SEPARATOR_S, first_element, ....)`. * (G_DIR_SEPARATOR_S, first_element, ....)`.
@ -2259,9 +2268,11 @@ g_build_filenamev (gchar **args)
* path. If the first element is a relative path, the result will * path. If the first element is a relative path, the result will
* be a relative path. * be a relative path.
* *
* Returns: (type filename) (transfer full): a newly-allocated string that * If you are building a path programmatically you may want to use
* must be freed with g_free(). * #GPathBuf instead.
**/ *
* Returns: (type filename) (transfer full): the newly allocated path
*/
gchar * gchar *
g_build_filename (const gchar *first_element, g_build_filename (const gchar *first_element,
...) ...)