diff --git a/gio/gfile.c b/gio/gfile.c index 3b4daff0f..a91346d32 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -86,94 +86,99 @@ typedef off_t loff_t; /** - * SECTION:gfile - * @short_description: File and Directory Handling - * @include: gio/gio.h - * @see_also: #GFileInfo, #GFileEnumerator + * GFile: * - * #GFile is a high level abstraction for manipulating files on a - * virtual file system. #GFiles are lightweight, immutable objects + * `GFile` is a high level abstraction for manipulating files on a + * virtual file system. `GFile`s are lightweight, immutable objects * that do no I/O upon creation. It is necessary to understand that - * #GFile objects do not represent files, merely an identifier for a + * `GFile` objects do not represent files, merely an identifier for a * file. All file content I/O is implemented as streaming operations - * (see #GInputStream and #GOutputStream). + * (see [class@Gio.InputStream] and [class@Gio.OutputStream]). * - * To construct a #GFile, you can use: - * - g_file_new_for_path() if you have a path. - * - g_file_new_for_uri() if you have a URI. - * - g_file_new_for_commandline_arg() for a command line argument. - * - g_file_new_tmp() to create a temporary file from a template. - * - g_file_new_tmp_async() to asynchronously create a temporary file. - * - g_file_new_tmp_dir_async() to asynchronously create a temporary directory. - * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). - * - g_file_new_build_filename() or g_file_new_build_filenamev() to create a file from path elements. + * To construct a `GFile`, you can use: * - * One way to think of a #GFile is as an abstraction of a pathname. For + * - [func@Gio.File.new_for_path] if you have a path. + * - [func@Gio.File.new_for_uri] if you have a URI. + * - [func@Gio.File.new_for_commandline_arg] or + * [func@Gio.File.new_for_commandline_arg_and_cwd] for a command line + * argument. + * - [func@Gio.File.new_tmp] to create a temporary file from a template. + * - [func@Gio.File.new_tmp_async] to asynchronously create a temporary file. + * - [func@Gio.File.new_tmp_dir_async] to asynchronously create a temporary + * directory. + * - [func@Gio.File.parse_name] from a UTF-8 string gotten from + * [method@Gio.File.get_parse_name]. + * - [func@Gio.File.new_build_filename] or [func@Gio.File.new_build_filenamev] + * to create a file from path elements. + * + * One way to think of a `GFile` is as an abstraction of a pathname. For * normal files the system pathname is what is stored internally, but as - * #GFiles are extensible it could also be something else that corresponds + * `GFile`s are extensible it could also be something else that corresponds * to a pathname in a userspace implementation of a filesystem. * - * #GFiles make up hierarchies of directories and files that correspond to + * `GFile`s make up hierarchies of directories and files that correspond to * the files on a filesystem. You can move through the file system with - * #GFile using g_file_get_parent() to get an identifier for the parent - * directory, g_file_get_child() to get a child within a directory, - * g_file_resolve_relative_path() to resolve a relative path between two - * #GFiles. There can be multiple hierarchies, so you may not end up at - * the same root if you repeatedly call g_file_get_parent() on two different - * files. + * `GFile` using [method@Gio.File.get_parent] to get an identifier for the + * parent directory, [method@Gio.File.get_child] to get a child within a + * directory, and [method@Gio.File.resolve_relative_path] to resolve a relative + * path between two `GFile`s. There can be multiple hierarchies, so you may not + * end up at the same root if you repeatedly call [method@Gio.File.get_parent] + * on two different files. * - * All #GFiles have a basename (get with g_file_get_basename()). These names - * are byte strings that are used to identify the file on the filesystem + * All `GFile`s have a basename (get with [method@Gio.File.get_basename]). These + * names are byte strings that are used to identify the file on the filesystem * (relative to its parent directory) and there is no guarantees that they * have any particular charset encoding or even make any sense at all. If * you want to use filenames in a user interface you should use the display * name that you can get by requesting the - * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). - * This is guaranteed to be in UTF-8 and can be used in a user interface. - * But always store the real basename or the #GFile to use to actually - * access the file, because there is no way to go from a display name to - * the actual name. + * `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with + * [method@Gio.File.query_info]. This is guaranteed to be in UTF-8 and can be + * used in a user interface. But always store the real basename or the `GFile` + * to use to actually access the file, because there is no way to go from a + * display name to the actual name. * - * Using #GFile as an identifier has the same weaknesses as using a path + * Using `GFile` as an identifier has the same weaknesses as using a path * in that there may be multiple aliases for the same file. For instance, - * hard or soft links may cause two different #GFiles to refer to the same + * hard or soft links may cause two different `GFile`s to refer to the same * file. Other possible causes for aliases are: case insensitive filesystems, * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to - * check if two #GFiles point to the same file you can query for the - * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial + * check if two `GFile`s point to the same file you can query for the + * `G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `GFile` does some trivial * canonicalization of pathnames passed in, so that trivial differences in * the path string used at creation (duplicated slashes, slash at end of - * path, "." or ".." path segments, etc) does not create different #GFiles. + * path, `.` or `..` path segments, etc) does not create different `GFile`s. * - * Many #GFile operations have both synchronous and asynchronous versions + * Many `GFile` operations have both synchronous and asynchronous versions * to suit your application. Asynchronous versions of synchronous functions - * simply have _async() appended to their function names. The asynchronous - * I/O functions call a #GAsyncReadyCallback which is then used to finalize - * the operation, producing a GAsyncResult which is then passed to the - * function's matching _finish() operation. + * simply have `_async()` appended to their function names. The asynchronous + * I/O functions call a [callback@Gio.AsyncReadyCallback] which is then used to + * finalize the operation, producing a [iface@Gio.AsyncResult] which is then + * passed to the function’s matching `_finish()` operation. * * It is highly recommended to use asynchronous calls when running within a * shared main loop, such as in the main thread of an application. This avoids * I/O operations blocking other sources on the main loop from being dispatched. * Synchronous I/O operations should be performed from worker threads. See the - * [introduction to asynchronous programming section][async-programming] for - * more. + * [introduction to asynchronous programming section](overview.html#asynchronous-programming) + * for more. * - * Some #GFile operations almost always take a noticeable amount of time, and + * Some `GFile` operations almost always take a noticeable amount of time, and * so do not have synchronous analogs. Notable cases include: - * - g_file_mount_mountable() to mount a mountable file. - * - g_file_unmount_mountable_with_operation() to unmount a mountable file. - * - g_file_eject_mountable_with_operation() to eject a mountable file. * - * ## Entity Tags # {#gfile-etag} + * - [method@Gio.File.mount_mountable] to mount a mountable file. + * - [method@Gio.File.unmount_mountable_with_operation] to unmount a mountable + * file. + * - [method@Gio.File.eject_mountable_with_operation] to eject a mountable file. * - * One notable feature of #GFiles are entity tags, or "etags" for + * ## Entity Tags + * + * One notable feature of `GFile`s are entity tags, or ‘etags’ for * short. Entity tags are somewhat like a more abstract version of the * traditional mtime, and can be used to quickly determine if the file * has been modified from the version on the file system. See the * HTTP 1.1 * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) - * for HTTP Etag headers, which are a very similar concept. + * for HTTP `ETag` headers, which are a very similar concept. */ static void g_file_real_query_info_async (GFile *file, @@ -1833,7 +1838,7 @@ g_file_create (GFile *file, /** * g_file_replace: * @file: input #GFile - * @etag: (nullable): an optional [entity tag][gfile-etag] + * @etag: (nullable): an optional [entity tag](#entity-tags) * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -2038,7 +2043,7 @@ g_file_create_readwrite (GFile *file, /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (nullable): an optional [entity tag][gfile-etag] + * @etag: (nullable): an optional [entity tag](#entity-tags) * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -2302,7 +2307,7 @@ g_file_create_finish (GFile *file, /** * g_file_replace_async: * @file: input #GFile - * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile, + * @etag: (nullable): an [entity tag](#entity-tags) for the current #GFile, * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -2526,7 +2531,7 @@ g_file_create_readwrite_finish (GFile *file, /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile, + * @etag: (nullable): an [entity tag](#entity-tags) for the current #GFile, * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -8309,11 +8314,11 @@ g_file_load_contents_finish (GFile *file, * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (nullable): the old [entity-tag][gfile-etag] for the document, + * @etag: (nullable): the old [entity-tag](#entity-tags) for the document, * or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (out) (optional) (nullable): a location to a new [entity tag][gfile-etag] + * @new_etag: (out) (optional) (nullable): a location to a new [entity tag](#entity-tags) * for the document. This should be freed with g_free() when no longer * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore @@ -8516,7 +8521,7 @@ replace_contents_open_callback (GObject *obj, * @file: input #GFile * @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @length: the length of @contents in bytes - * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL + * @etag: (nullable): a new [entity tag](#entity-tags) for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -8566,7 +8571,7 @@ g_file_replace_contents_async (GFile *file, * g_file_replace_contents_bytes_async: * @file: input #GFile * @contents: a #GBytes - * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL + * @etag: (nullable): a new [entity tag](#entity-tags) for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -8621,7 +8626,7 @@ g_file_replace_contents_bytes_async (GFile *file, * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (optional) (nullable): a location of a new [entity tag][gfile-etag] + * @new_etag: (out) (optional) (nullable): a location of a new [entity tag](#entity-tags) * for the document. This should be freed with g_free() when it is no * longer needed, or %NULL * @error: a #GError, or %NULL diff --git a/gio/gfile.h b/gio/gfile.h index 7c43fe070..b45689ee6 100644 --- a/gio/gfile.h +++ b/gio/gfile.h @@ -36,16 +36,6 @@ G_BEGIN_DECLS #define G_IS_FILE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_FILE)) #define G_FILE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE, GFileIface)) -#if 0 -/** - * GFile: - * - * A handle to an object implementing the #GFileIface interface. - * Generally stores a location within the file system. Handles do not - * necessarily represent files or directories that currently exist. - **/ -typedef struct _GFile GFile; /* Dummy typedef */ -#endif typedef struct _GFileIface GFileIface; diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c index e4302a99b..127532a6b 100644 --- a/gio/gfileinfo.c +++ b/gio/gfileinfo.c @@ -2066,7 +2066,7 @@ g_file_info_get_symlink_target (GFileInfo *info) * g_file_info_get_etag: * @info: a #GFileInfo. * - * Gets the [entity tag][gfile-etag] for a given + * Gets the [entity tag](iface.File.html#entity-tags) for a given * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * * It is an error to call this if the #GFileInfo does not contain diff --git a/gio/giotypes.h b/gio/giotypes.h index 82e091bef..c2ed2b8f3 100644 --- a/gio/giotypes.h +++ b/gio/giotypes.h @@ -76,13 +76,6 @@ typedef struct _GFileMonitor GFileMonitor; typedef struct _GFilterInputStream GFilterInputStream; typedef struct _GFilterOutputStream GFilterOutputStream; -/** - * GFile: - * - * A handle to an object implementing the #GFileIface interface. - * Generally stores a location within the file system. Handles do not - * necessarily represent files or directories that currently exist. - **/ typedef struct _GFile GFile; /* Dummy typedef */ typedef struct _GFileInfo GFileInfo;