From f509a1f2300261188b7cfa5cdfa71e5a1a30b3a3 Mon Sep 17 00:00:00 2001 From: Kjell Ahlstedt Date: Fri, 2 Sep 2022 16:50:54 +0200 Subject: Gio::File docs: Add @throws and other minor documentation fixes. --- gio/src/file.hg | 148 ++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 116 insertions(+), 32 deletions(-) diff --git a/gio/src/file.hg b/gio/src/file.hg index 0ff074f2..e4224f8c 100644 --- a/gio/src/file.hg +++ b/gio/src/file.hg @@ -270,6 +270,8 @@ public: * @param flags A set of CreateFlags. * @param cancellable Optional Cancellable object. * @return A FileOutputStream. + * + * @throws Gio::Error */ Glib::RefPtr append_to(const Glib::RefPtr& cancellable, CreateFlags flags = CreateFlags::NONE); @@ -288,6 +290,8 @@ public: * filesystem the file is on. * @param flags A set of CreateFlags. * @return A FileOutputStream. + * + * @throws Gio::Error */ Glib::RefPtr append_to(CreateFlags flags = CreateFlags::NONE); _IGNORE(g_file_append_to) @@ -319,6 +323,8 @@ public: * @param cancellable A Cancellable object which can be used to cancel the operation. * @param flags a set of CreateFlags. * @return A FileOutputStream for the newly created file. + * + * @throws Gio::Error */ Glib::RefPtr create_file(const Glib::RefPtr& cancellable, CreateFlags flags = CreateFlags::NONE); @@ -342,6 +348,8 @@ public: * * @param flags a set of CreateFlags. * @return A FileOutputStream for the newly created file. + * + * @throws Gio::Error */ Glib::RefPtr create_file(CreateFlags flags = CreateFlags::NONE); _IGNORE(g_file_create) @@ -374,6 +382,8 @@ public: * @param cancellable A Cancellable object which can be used to cancel the operation. * @param flags a set of CreateFlags. * @return A FileOutputStream for the newly created file. + * + * @throws Gio::Error */ Glib::RefPtr create_file_readwrite(const Glib::RefPtr& cancellable, CreateFlags flags = CreateFlags::NONE); @@ -401,12 +411,12 @@ public: * * @param flags a set of CreateFlags. * @return A FileOutputStream for the newly created file. + * + * @throws Gio::Error */ Glib::RefPtr create_file_readwrite(CreateFlags flags = CreateFlags::NONE); _IGNORE(g_file_create_readwrite) - - /** Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. * This will try to replace the file in the safest way possible so that any errors during the writing will * not affect an already existing copy of the file. For instance, for local files it may write to a @@ -440,10 +450,11 @@ public: * @param make_backup true if a backup should be created. * @param flags A set of CreateFlags. * @return A FileOutputStream. + * + * @throws Gio::Error */ Glib::RefPtr replace(const Glib::RefPtr& cancellable, const std::string& etag = {}, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); - /** Returns an output stream for overwriting the file, possibly creating a backup copy of the file first. * This will try to replace the file in the safest way possible so that any errors during the writing will * not affect an already existing copy of the file. For instance, for local files it may write to a @@ -473,12 +484,13 @@ public: * @param make_backup true if a backup should be created. * @param flags A set of CreateFlags. * @return A FileOutputStream. + * + * @throws Gio::Error */ Glib::RefPtr replace(const std::string& etag = {}, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); _IGNORE(g_file_replace) - /** Asynchronously opens the file for appending. * For more details, see append_to() which is the synchronous version of this call. * @@ -669,6 +681,8 @@ public: * @param flags A set of CreateFlags. * @return A FileOutputStream. * + * @throws Gio::Error + * * @newin{2,24} */ Glib::RefPtr replace_readwrite(const Glib::RefPtr& cancellable, const std::string& etag = {}, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); @@ -689,6 +703,8 @@ public: * @param flags A set of CreateFlags. * @return A FileOutputStream. * + * @throws Gio::Error + * * @newin{2,24} */ Glib::RefPtr replace_readwrite(const std::string& etag = {}, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); @@ -763,6 +779,8 @@ public: * @param attributes: An attribute query string. * @param flags: A set of FileQueryInfoFlags. * @result a FileInfo for the file, or an empty RefPtr on error. + * + * @throws Gio::Error */ Glib::RefPtr query_info(const Glib::RefPtr& cancellable, const std::string& attributes = "*", FileQueryInfoFlags flags = FileQueryInfoFlags::NONE) const; @@ -791,6 +809,8 @@ public: * @param attributes: An attribute query string. * @param flags: A set of FileQueryInfoFlags. * @result a FileInfo for the file, or an empty RefPtr on error. + * + * @throws Gio::Error */ Glib::RefPtr query_info(const std::string& attributes = "*", FileQueryInfoFlags flags = FileQueryInfoFlags::NONE) const; @@ -808,7 +828,7 @@ public: * directory, or symlink. * * @param flags: a set of FileQueryInfoFlags passed to query_info(). - * @result The FileType of the file, or FILE_TYPE_UNKNOWN if the file does not exist. + * @result The FileType of the file, or FileType::UNKNOWN if the file does not exist. * * @newin{2,18} */ @@ -866,9 +886,12 @@ public: * * If the file does not exist, a Gio::Error with NOT_FOUND will be thrown. * Other errors are possible too, and depend on what kind of filesystem the file is on. + * * @param cancellable A Cancellable object. * @param attributes An attribute query string. * @return A FileInfo or an empty RefPtr if there was an error. + * + * @throws Gio::Error */ Glib::RefPtr query_filesystem_info(const Glib::RefPtr& cancellable, const std::string& attributes = "*"); @@ -887,11 +910,13 @@ public: * (the total size of the filesystem in bytes), FILE_ATTRIBUTE_FILESYSTEM_FREE (number of * bytes availible), and FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). * - * * If the file does not exist, a Gio::Error with NOT_FOUND will be thrown. * Other errors are possible too, and depend on what kind of filesystem the file is on. + * * @param attributes An attribute query string. * @return A FileInfo or an empty RefPtr if there was an error. + * + * @throws Gio::Error */ Glib::RefPtr query_filesystem_info(const std::string& attributes = "*"); _IGNORE(g_file_query_filesystem_info) @@ -990,6 +1015,8 @@ public: * @param attributes An attribute query string. * @param flags A set of FileQueryInfoFlags. * @return A FileEnumerator if successful. + * + * @throws Gio::Error */ Glib::RefPtr enumerate_children(const Glib::RefPtr& cancellable, const std::string& attributes = "*", FileQueryInfoFlags flags = FileQueryInfoFlags::NONE); _IGNORE(g_file_enumerate_children) @@ -1013,12 +1040,12 @@ public: * @param attributes An attribute query string. * @param flags A set of FileQueryInfoFlags. * @return A FileEnumerator if successful. + * + * @throws Gio::Error */ Glib::RefPtr enumerate_children(const std::string& attributes = "*", FileQueryInfoFlags flags = FileQueryInfoFlags::NONE); _IGNORE(g_file_enumerate_children) - - /** Asynchronously gets the requested information about the files in a directory. The result is a GFileEnumerator object that will give out GFileInfo objects for all the files in the directory. * * For more details, see enumerate_children() which is the synchronous version of this call. @@ -1171,6 +1198,8 @@ public: * then a Gio::Error with WOULD_RECURSE will be thrown. * * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup(). + * + * @throws Gio::Error */ bool copy(const Glib::RefPtr& destination, const SlotFileProgress& slot, const Glib::RefPtr& cancellable, CopyFlags flags = CopyFlags::NONE); @@ -1191,6 +1220,8 @@ public: * then a Gio::Error with WOULD_RECURSE will be thrown. * * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup(). + * + * @throws Gio::Error */ bool copy(const Glib::RefPtr& destination, const SlotFileProgress& slot, CopyFlags flags = CopyFlags::NONE); @@ -1209,6 +1240,8 @@ public: * then a Gio::Error with WOULD_RECURSE will be thrown. * * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup(). + * + * @throws Gio::Error */ bool copy(const Glib::RefPtr& destination, CopyFlags flags = CopyFlags::NONE); _IGNORE(g_file_copy) @@ -1300,7 +1333,10 @@ public: * If trying to overwrite a file over a directory a Gio::Error with IS_DIRECTORY will be thrown. * If trying to overwrite a directory with a directory a Gio::Error with WOULD_MERGE will be thrown. * - * If the source is a directory and the target does not exist, or CopyFlags::OVERWRITE is specified and the target is a file, then a Gio::Error with WOULD_RECURSE may be thrown (if the native move operation isn't available). + * If the source is a directory and the target does not exist, or CopyFlags::OVERWRITE is specified and the target is a file, + * then a Gio::Error with WOULD_RECURSE may be thrown (if the native move operation isn't available). + * + * @throws Gio::Error */ bool move(const Glib::RefPtr& destination, const SlotFileProgress& slot, const Glib::RefPtr& cancellable, CopyFlags flags = CopyFlags::NONE); @@ -1426,6 +1462,8 @@ public: * @param cancellable A Cancellable object which can be used to cancel the operation. * @param flags A set of FileQueryInfoFlags. * @return true if there was any error, false otherwise. + * + * @throws Gio::Error */ bool set_attributes_from_info(const Glib::RefPtr& info, const Glib::RefPtr& cancellable, FileQueryInfoFlags flags = FileQueryInfoFlags::NONE); @@ -1444,6 +1482,8 @@ public: * @param info A FileInfo. * @param flags A set of FileQueryInfoFlags. * @return true if there was any error, false otherwise. + * + * @throws Gio::Error */ bool set_attributes_from_info(const Glib::RefPtr& info, FileQueryInfoFlags flags = FileQueryInfoFlags::NONE); _IGNORE(g_file_set_attributes_from_info) @@ -1550,7 +1590,7 @@ public: g_file_mount_enclosing_volume_finish, errthrow) - /** Mounts a file of type FILE_TYPE_MOUNTABLE. Using @a mount_operation, you can request callbacks when, for instance, + /** Mounts a file of type FileType::MOUNTABLE. Using @a mount_operation, you can request callbacks when, for instance, * passwords are needed during authentication. * * The operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, @@ -1565,7 +1605,7 @@ public: */ void mount_mountable(const Glib::RefPtr& mount_operation, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, Mount::MountFlags flags = Mount::MountFlags::NONE); - /** Mounts a file of type FILE_TYPE_MOUNTABLE. Using @a mount_operation, you can request callbacks when, for instance, + /** Mounts a file of type FileType::MOUNTABLE. Using @a mount_operation, you can request callbacks when, for instance, * passwords are needed during authentication. * * When the operation is finished, @a slot will be called. You can then call mount_mountable_finish() to get the result of the operation. @@ -1576,7 +1616,7 @@ public: */ void mount_mountable(const Glib::RefPtr& mount_operation, const SlotAsyncReady& slot, Mount::MountFlags flags = Mount::MountFlags::NONE); - /** Mounts a file of type FILE_TYPE_MOUNTABLE without user interaction. + /** Mounts a file of type FileType::MOUNTABLE without user interaction. * * When the operation is finished, @a slot will be called. You can then call mount_mountable_finish() to get the result of the operation. * @@ -1585,7 +1625,7 @@ public: */ void mount_mountable(const SlotAsyncReady& slot, Mount::MountFlags flags = Mount::MountFlags::NONE); - /** Mounts a file of type FILE_TYPE_MOUNTABLE without user interaction. + /** Mounts a file of type FileType::MOUNTABLE without user interaction. * * @param flags Flags affecting the operation. */ @@ -1596,7 +1636,7 @@ public: g_file_mount_mountable_finish, errthrow) - /** Unmounts a file of type FILE_TYPE_MOUNTABLE. + /** Unmounts a file of type FileType::MOUNTABLE. * * The operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, * a Gio::Error with CANCELLED will be thrown. @@ -1609,7 +1649,7 @@ public: */ void unmount_mountable(const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, Mount::UnmountFlags flags = Mount::UnmountFlags::NONE); - /** Unmounts a file of type FILE_TYPE_MOUNTABLE. + /** Unmounts a file of type FileType::MOUNTABLE. * * When the operation is finished, @a slot will be called. You can then call unmount_mountable_finish() to get the result of the operation. * @@ -1618,13 +1658,13 @@ public: */ void unmount_mountable(const SlotAsyncReady& slot, Mount::UnmountFlags flags = Mount::UnmountFlags::NONE); - /** Unmounts a file of type FILE_TYPE_MOUNTABLE. + /** Unmounts a file of type FileType::MOUNTABLE. * * @param flags Flags affecting the operation. */ void unmount_mountable(Mount::UnmountFlags flags = Mount::UnmountFlags::NONE); - /** Unmounts a file of type FILE_TYPE_MOUNTABLE. + /** Unmounts a file of type FileType::MOUNTABLE. * * The operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, * a Gio::Error with CANCELLED will be thrown. @@ -1640,7 +1680,7 @@ public: */ void unmount_mountable(const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, const Glib::RefPtr& mount_operation, Mount::UnmountFlags flags = Mount::UnmountFlags::NONE); - /** Unmounts a file of type FILE_TYPE_MOUNTABLE. + /** Unmounts a file of type FileType::MOUNTABLE. * * When the operation is finished, @a slot will be called. You can then call unmount_mountable_finish() to get the result of the operation. * @@ -1652,7 +1692,7 @@ public: */ void unmount_mountable(const SlotAsyncReady& slot, const Glib::RefPtr& mount_operation, Mount::UnmountFlags flags = Mount::UnmountFlags::NONE); - /** Unmounts a file of type FILE_TYPE_MOUNTABLE. + /** Unmounts a file of type FileType::MOUNTABLE. * * @param mount_operation A MountOperation * @param flags Flags affecting the operation. @@ -1751,6 +1791,8 @@ public: * @param cancellable A Cancellable object. * @param flags A set of FileMonitorFlags. * @result true if the attributes were copied successfully, false otherwise. + * + * @throws Gio::Error */ bool copy_attributes(const Glib::RefPtr& destination, const Glib::RefPtr& cancellable, CopyFlags flags = CopyFlags::NONE); @@ -1765,6 +1807,8 @@ public: * @param destination A File to copy attributes to. * @param flags A set of FileMonitorFlags. * @result true if the attributes were copied successfully, false otherwise. + * + * @throws Gio::Error */ bool copy_attributes(const Glib::RefPtr& destination, CopyFlags flags = CopyFlags::NONE); _IGNORE(g_file_copy_attributes) @@ -1778,6 +1822,8 @@ public: * @param cancellable A Cancellable object. * @param flags A set of FileMonitorFlags. * @return A FileMonitor for the file. + * + * @throws Gio::Error */ Glib::RefPtr monitor_directory(const Glib::RefPtr& cancellable, FileMonitorFlags flags = FileMonitorFlags::NONE); @@ -1786,6 +1832,8 @@ public: * * @param flags A set of FileMonitorFlags. * @return A FileMonitor for the file. + * + * @throws Gio::Error */ Glib::RefPtr monitor_directory(FileMonitorFlags flags = FileMonitorFlags::NONE); _IGNORE(g_file_monitor_directory) @@ -1799,6 +1847,8 @@ public: * @param cancellable A Cancellable object. * @param flags A set of FileMonitorFlags. * @return A FileMonitor for the file. + * + * @throws Gio::Error */ Glib::RefPtr monitor_file(const Glib::RefPtr& cancellable, FileMonitorFlags flags = FileMonitorFlags::NONE); @@ -1810,6 +1860,8 @@ public: * * @param flags A set of FileMonitorFlags. * @return A FileMonitor for the file. + * + * @throws Gio::Error */ Glib::RefPtr monitor_file(FileMonitorFlags flags = FileMonitorFlags::NONE); _IGNORE(g_file_monitor_file) @@ -1825,6 +1877,8 @@ public: * @param flags A set of FileMonitorFlags. * @return A FileMonitor for the file. * + * @throws Gio::Error + * * @newin{2,18} */ Glib::RefPtr monitor(const Glib::RefPtr& cancellable, FileMonitorFlags flags = FileMonitorFlags::NONE); @@ -1838,6 +1892,8 @@ public: * @param flags A set of FileMonitorFlags. * @return A FileMonitor for the file. * + * @throws Gio::Error + * * @newin{2,18} */ Glib::RefPtr monitor(FileMonitorFlags flags = FileMonitorFlags::NONE); @@ -1894,7 +1950,7 @@ public: * * By default, errors are only reported against the toplevel file * itself. Errors found while recursing are silently ignored, unless - * FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @a flags. + * MeasureFlags::REPORT_ANY_ERROR is given in @a flags. * * The returned size, @a disk_usage, is in bytes and should be formatted * with g_format_size() in order to get something reasonable for showing @@ -1913,6 +1969,8 @@ public: * @param num_dirs The number of directories encountered. * @param num_files The number of non-directories encountered. * @param flags Set of MeasureFlags. + * + * @throws Gio::Error */ void measure_disk_usage(const Glib::RefPtr& cancellable, const SlotFileMeasureProgress& slot_progress, guint64& disk_usage, guint64& num_dirs, guint64& num_files, MeasureFlags flags = MeasureFlags::NONE); _IGNORE(g_file_measure_disk_usage) @@ -2084,6 +2142,8 @@ public: * @param contents A location to place the contents of the file. * @param length A location to place the length of the contents of the file. * @param etag_out A location to place the current entity tag for the file. + * + * @throws Gio::Error */ bool load_contents(const Glib::RefPtr& cancellable, char*& contents, gsize& length, std::string& etag_out); @@ -2097,6 +2157,8 @@ public: * @param contents A location to place the contents of the file. * @param length A location to place the length of the contents of the file. * @newin{2,22} + * + * @throws Gio::Error */ bool load_contents(const Glib::RefPtr& cancellable, char*& contents, gsize& length); @@ -2107,6 +2169,8 @@ public: * @param contents A location to place the contents of the file. * @param length A location to place the length of the contents of the file. * @param etag_out A location to place the current entity tag for the file. + * + * @throws Gio::Error */ bool load_contents(char*& contents, gsize& length, std::string& etag_out); @@ -2116,6 +2180,8 @@ public: * @param contents A location to place the contents of the file. * @param length A location to place the length of the contents of the file. * @newin{2,22} + * + * @throws Gio::Error */ bool load_contents(char*& contents, gsize& length); _IGNORE(g_file_load_contents) @@ -2155,6 +2221,8 @@ public: * @param etag_out A location to place the current entity tag for the file. * @return true if the load was successful. If false and @a error is * present, it will be set appropriately. + * + * @throws Gio::Error */ bool load_contents_finish(const Glib::RefPtr& result, char*& contents, gsize& length, std::string& etag_out); @@ -2168,6 +2236,8 @@ public: * @return true if the load was successful. If false and @a error is * present, it will be set appropriately. * @newin{2,22} + * + * @throws Gio::Error */ bool load_contents_finish(const Glib::RefPtr& result, char*& contents, gsize& length); _IGNORE(g_file_load_contents_finish) @@ -2218,6 +2288,8 @@ public: * @param etag_out A location to place the current entity tag for the file. * @return true if the load was successful. If false and @a error is * present, it will be set appropriately. + * + * @throws Gio::Error */ bool load_partial_contents_finish(const Glib::RefPtr& result, char*& contents, gsize& length, std::string& etag_out); @@ -2229,6 +2301,8 @@ public: * @return true if the load was successful. If false and @a error is * present, it will be set appropriately. * @newin{2,22} + * + * @throws Gio::Error */ bool load_partial_contents_finish(const Glib::RefPtr& result, char*& contents, gsize& length); _IGNORE(g_file_load_partial_contents_finish) @@ -2246,15 +2320,17 @@ public: * * The returned @a new_etag can be used to verify that the file hasn't changed the * next time it is saved over. + * * @param contents A string containing the new contents for the file. * @param length The length of @a contents in bytes. * @param etag The old entity tag * for the document. * @param make_backup true if a backup should be created. * @param flags A set of CreateFlags. - * @param new_etag A location to a new entity tag - * for the document. + * @param new_etag A location to a new entity tag for the document. * @param cancellable A Cancellable object. + * + * @throws Gio::Error */ void replace_contents(const char* contents, gsize length, const std::string& etag, std::string& new_etag, const Glib::RefPtr& cancellable, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); @@ -2267,14 +2343,16 @@ public: * * The returned @a new_etag can be used to verify that the file hasn't changed the * next time it is saved over. + * * @param contents A string containing the new contents for the file. * @param length The length of @a contents in bytes. * @param etag The old entity tag * for the document. * @param make_backup true if a backup should be created. * @param flags A set of CreateFlags. - * @param new_etag A location to a new entity tag - * for the document. + * @param new_etag A location to a new entity tag for the document. + * + * @throws Gio::Error */ void replace_contents(const char* contents, gsize length, const std::string& etag, std::string& new_etag, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); @@ -2291,14 +2369,16 @@ public: * * The returned @a new_etag can be used to verify that the file hasn't changed the * next time it is saved over. + * * @param contents A string containing the new contents for the file. * @param etag The old entity tag * for the document. * @param make_backup true if a backup should be created. * @param flags A set of CreateFlags. - * @param new_etag A location to a new entity tag - * for the document. + * @param new_etag A location to a new entity tag for the document. * @param cancellable A Cancellable object. + * + * @throws Gio::Error */ void replace_contents(const std::string& contents, const std::string& etag, std::string& new_etag, const Glib::RefPtr& cancellable, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); @@ -2311,13 +2391,15 @@ public: * * The returned @a new_etag can be used to verify that the file hasn't changed the * next time it is saved over. + * * @param contents A string containing the new contents for the file. * @param etag The old entity tag * for the document. * @param make_backup true if a backup should be created. * @param flags A set of CreateFlags. - * @param new_etag A location to a new entity tag - * for the document. + * @param new_etag A location to a new entity tag for the document. + * + * @throws Gio::Error */ void replace_contents(const std::string& contents, const std::string& etag, std::string& new_etag, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); _IGNORE(g_file_replace_contents) @@ -2420,8 +2502,9 @@ public: * replace_contents_async(). Sets @a new_etag to the new entity * tag for the document. * @param result A AsyncResult. - * @param new_etag A location of a new entity tag - * for the document. + * @param new_etag A location of a new entity tag for the document. + * + * @throws Gio::Error */ void replace_contents_finish(const Glib::RefPtr& result, std::string& new_etag); @@ -2429,7 +2512,8 @@ public: * replace_contents_async(). Sets @a new_etag to the new entity * tag for the document. * @param result A AsyncResult. - * for the document. + * + * @throws Gio::Error */ void replace_contents_finish(const Glib::RefPtr& result); _IGNORE(g_file_replace_contents_finish) @@ -2476,7 +2560,7 @@ public: */ void replace_contents_bytes_async(const SlotAsyncReady& slot, const Glib::RefPtr& contents, const std::string& etag, bool make_backup = false, CreateFlags flags = CreateFlags::NONE); - _IGNORE(g_file_replace_contents_async) + _IGNORE(g_file_replace_contents_bytes_async) _WRAP_METHOD(bool supports_thread_contexts() const, g_file_supports_thread_contexts) -- cgit v1.2.1