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.

glib/gfileutils.c

@@ -1597,8 +1597,8 @@ wrap_g_open (const gchar *filename,
  * g_dir_make_tmp() instead.
  *
  * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
- *     modified to hold the directory name. In case of errors, %NULL is
+ *   modified to hold the directory name. In case of errors, %NULL is
- *     returned, and %errno will be set.
+ *   returned, and %errno will be set.
  *
  * Since: 2.30
  */
@@ -1633,8 +1633,8 @@ g_mkdtemp_full (gchar *tmpl,
  * g_dir_make_tmp() instead.
  *
  * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
- *     modified to hold the directory name.  In case of errors, %NULL is
+ *   modified to hold the directory name.  In case of errors, %NULL is
- *     returned and %errno will be set.
+ *   returned and %errno will be set.
  *
  * Since: 2.30
  */
@@ -1648,7 +1648,7 @@ g_mkdtemp (gchar *tmpl)
  * g_mkstemp_full: (skip)
  * @tmpl: (type filename): template filename
  * @flags: flags to pass to an open() call in addition to O_EXCL
- *     and O_CREAT, which are passed automatically
+ *   and O_CREAT, which are passed automatically
  * @mode: permissions to create the temporary file with
  *
  * Opens a temporary file. See the mkstemp() documentation
@@ -1664,9 +1664,9 @@ g_mkdtemp (gchar *tmpl)
  * on Windows it should be in UTF-8.
  *
  * Returns: A file handle (as from open()) to the file
- *     opened for reading and writing. The file handle should be
+ *   opened for reading and writing. The file handle should be
- *     closed with close(). In case of errors, -1 is returned
+ *   closed with close(). In case of errors, -1 is returned
- *     and %errno will be set.
+ *   and %errno will be set.
  *
  * Since: 2.22
  */
@@ -1696,10 +1696,10 @@ g_mkstemp_full (gchar *tmpl,
  * Most importantly, on Windows it should be in UTF-8.
  *
  * Returns: A file handle (as from open()) to the file
- *     opened for reading and writing. The file is opened in binary
+ *   opened for reading and writing. The file is opened in binary
- *     mode on platforms where there is a difference. The file handle
+ *   mode on platforms where there is a difference. The file handle
- *     should be closed with close(). In case of errors, -1 is
+ *   should be closed with close(). In case of errors, -1 is
- *     returned and %errno will be set.
+ *   returned and %errno will be set.
  */
 gint
 g_mkstemp (gchar *tmpl)
@@ -1787,9 +1787,9 @@ g_get_tmp_name (const gchar      *tmpl,
 /**
  * g_file_open_tmp:
  * @tmpl: (type filename) (nullable): Template for file name, as in
- *     g_mkstemp(), basename only, or %NULL for a default template
+ *   g_mkstemp(), basename only, or %NULL for a default template
  * @name_used: (out) (type filename): location to store actual name used,
- *     or %NULL
+ *   or %NULL
  * @error: return location for a #GError
  *
  * Opens a file for writing in the preferred directory for temporary
@@ -1810,9 +1810,9 @@ g_get_tmp_name (const gchar      *tmpl,
  * name encoding.
  *
  * Returns: A file handle (as from open()) to the file opened for
- *     reading and writing. The file is opened in binary mode on platforms
+ *   reading and writing. The file is opened in binary mode on platforms
- *     where there is a difference. The file handle should be closed with
+ *   where there is a difference. The file handle should be closed with
- *     close(). In case of errors, -1 is returned and @error will be set.
+ *   close(). In case of errors, -1 is returned and @error will be set.
  */
 gint
 g_file_open_tmp (const gchar  *tmpl,
@@ -1843,7 +1843,7 @@ g_file_open_tmp (const gchar  *tmpl,
 /**
  * g_dir_make_tmp:
  * @tmpl: (type filename) (nullable): Template for directory name,
- *     as in g_mkdtemp(), basename only, or %NULL for a default template
+ *   as in g_mkdtemp(), basename only, or %NULL for a default template
  * @error: return location for a #GError
  *
  * Creates a subdirectory in the preferred directory for temporary
@@ -1859,9 +1859,9 @@ g_file_open_tmp (const gchar  *tmpl,
  * modified, and might thus be a read-only literal string.
  *
  * Returns: (type filename) (transfer full): The actual name used. This string
- *     should be freed with g_free() when not needed any longer and is
+ *   should be freed with g_free() when not needed any longer and is
- *     is in the GLib file name encoding. In case of errors, %NULL is
+ *   is in the GLib file name encoding. In case of errors, %NULL is
- *     returned and @error will be set.
+ *   returned and @error will be set.
  *
  * Since: 2.30
  */
@@ -1986,11 +1986,12 @@ g_build_path_va (const gchar  *separator,
  * g_build_pathv:
  * @separator: a string used to separator the elements of the path.
  * @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_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
  *     must be freed with g_free().
@@ -2015,10 +2016,12 @@ g_build_pathv (const gchar  *separator,
  * @...: remaining elements in path, terminated by %NULL
  * 
  * 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.
  *
@@ -2279,14 +2282,15 @@ g_build_filename (const gchar *first_element,
  * @error: return location for a #GError
  *
  * 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_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error);
  *
@@ -2302,7 +2306,7 @@ g_build_filename (const gchar *first_element,
  * ]|
  *
  * Returns: (type filename) (transfer full): A newly-allocated string with
- *     the contents of the symbolic link, or %NULL if an error occurred.
+ *   the contents of the symbolic link, or %NULL if an error occurred.
  *
  * Since: 2.4
  */
@@ -2509,12 +2513,12 @@ g_path_skip_root (const gchar *file_name)
  * string.
  *
  * Returns: (type filename): the name of the file without any leading
- *     directory components
+ *   directory components
  *
  * Deprecated:2.2: Use g_path_get_basename() instead, but notice
- *     that g_path_get_basename() allocates new memory for the
+ *   that g_path_get_basename() allocates new memory for the
- *     returned string, unlike this function which returns a pointer
+ *   returned string, unlike this function which returns a pointer
- *     into the argument.
+ *   into the argument.
  */
 const gchar *
 g_basename (const gchar *file_name)
@@ -2557,7 +2561,7 @@ g_basename (const gchar *file_name)
  * separator is returned. If @file_name is empty, it gets ".".
  *
  * Returns: (type filename) (transfer full): a newly allocated string
- *    containing the last component of the filename
+ *   containing the last component of the filename
  */
 gchar *
 g_path_get_basename (const gchar *file_name)
@@ -2751,7 +2755,8 @@ g_path_get_dirname (const gchar *file_name)
  * No file system I/O is done.
  *
  * Returns: (type filename) (transfer full): a newly allocated string with the
- * canonical file path
+ *   canonical file path
+ *
  * Since: 2.58
  */
 gchar *