From 54e52e099e11e0fd6541ce97c16b9f2dd381eb91 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 28 Nov 2007 06:01:13 +0000 Subject: [PATCH] More trivial doc fixes svn path=/trunk/; revision=5968 --- gio/ChangeLog | 6 ++ gio/gappinfo.c | 2 +- gio/gcontenttype.c | 171 +++++++++++++++++++++------------------------- gio/gdesktopappinfo.c | 21 +++--- gio/gdrive.c | 5 +- gio/gfile.c | 77 ++++++++++----------- gio/gfileattribute.c | 3 +- gio/gfileinfo.h | 2 +- gio/gfilemonitor.c | 4 +- gio/gfilenamecompleter.c | 9 ++- gio/gfilterinputstream.c | 2 + gio/gfilteroutputstream.c | 8 +++ gio/goutputstream.c | 3 +- gio/gsimpleasyncresult.c | 57 +++++++++------- gio/gunionvolumemonitor.c | 7 +- 15 files changed, 199 insertions(+), 178 deletions(-) diff --git a/gio/ChangeLog b/gio/ChangeLog index 5baf136..211d1b0 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,5 +1,11 @@ 2007-11-27 Matthias Clasen + * gcontenttype.c: Move doc comments to the unix section. + + * *.[hc]: More trivial doc corrections. + +2007-11-27 Matthias Clasen + * gpollfilemonitor.c: * gunixmounts.c: * gvfs.c: diff --git a/gio/gappinfo.c b/gio/gappinfo.c index eb26f6b..96781ef 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -307,7 +307,7 @@ g_app_info_add_supports_type (GAppInfo *appinfo, /** - * g_app_info_can_remove_support_type: + * g_app_info_can_remove_supports_type: * @appinfo: a #GAppInfo. * * Checks if a supported content type can be removed from an application. diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c index c3f2079..84037ce 100644 --- a/gio/gcontenttype.c +++ b/gio/gcontenttype.c @@ -28,11 +28,6 @@ #include "gcontenttypeprivate.h" #include "glibintl.h" -/* This really sucks. GTK-Doc isn't smart enough to realize there are two - * different versions of the functions within this file, based on the platform. - * I can move the definitions out of this file, but that's ugly. - */ - /** * SECTION:gcontenttype * @short_description: platform specific content typing @@ -82,16 +77,6 @@ get_registry_classes_key (const char *subdir, return value_utf8; } -/** - * g_content_type_equals: - * @type1: a content type string. - * @type2: a content type string. - * - * Compares two content types for equality. - * - * Returns: %TRUE if the two strings are identical or equivalent, - * %FALSE otherwise. - **/ gboolean g_content_type_equals (const char *type1, const char *type2) @@ -117,16 +102,6 @@ g_content_type_equals (const char *type1, return res; } -/** - * g_content_type_is_a: - * @type: a content type string. - * @supertype: a string. - * - * Determines if @type is a subset of @supertype. - * - * Returns: %TRUE if @type is a kind of @supertype, - * %FALSE otherwise. - **/ gboolean g_content_type_is_a (const char *type, const char *supertype) @@ -149,14 +124,6 @@ g_content_type_is_a (const char *type, return res; } -/** - * g_content_type_is_unknown: - * @type: a content type string. - * - * Checks if the content type is known by GIO. - * - * Returns: %TRUE if the type is unknown. - **/ gboolean g_content_type_is_unknown (const char *type) { @@ -165,14 +132,6 @@ g_content_type_is_unknown (const char *type) return strcmp ("*", type) == 0; } -/** - * g_content_type_get_description: - * @type: a content type string. - * - * Gets the human readable description of the content type. - * - * Returns: a short description of the content type @type. - **/ char * g_content_type_get_description (const char *type) { @@ -196,14 +155,6 @@ g_content_type_get_description (const char *type) return g_strdup_printf (_("%s filetype"), type); } -/** - * g_content_type_get_mime_type: - * @type: a content type string. - * - * Gets the mime-type for the content type. - * - * Returns: the registered mime-type for the given @type. - **/ char * g_content_type_get_mime_type (const char *type) { @@ -223,14 +174,6 @@ g_content_type_get_mime_type (const char *type) return g_strdup ("application/octet-stream"); } -/** - * g_content_type_get_icon: - * @type: a content type string. - * - * Gets the icon for a content type. - * - * Returns: #GIcon corresponding to the content type. - **/ GIcon * g_content_type_get_icon (const char *type) { @@ -246,16 +189,6 @@ g_content_type_get_icon (const char *type) return NULL; } -/** - * g_content_type_can_be_executable: - * @type: a content type string. - * - * Checks if a content type can be executable. Note that for instance - * things like text files can be executables (i.e. scripts and batch files). - * - * Returns: %TRUE if the file type corresponds to a type that - * can be executable, %FALSE otherwise. - **/ gboolean g_content_type_can_be_executable (const char *type) { @@ -282,20 +215,6 @@ looks_like_text (const guchar *data, gsize data_size) return TRUE; } -/** - * g_content_type_guess: - * @filename: a string. - * @data: a stream of data. - * @data_size: the size of @data. - * @result_uncertain: a flag indicating the certainty of the - * result. - * - * Guesses the content type based on example data. If the function is - * uncertain, @result_uncertain will be set to %TRUE. - * - * Returns: a string indicating a guessed content type for the - * given data. - **/ char * g_content_type_guess (const char *filename, const guchar *data, @@ -326,14 +245,6 @@ g_content_type_guess (const char *filename, return g_strdup ("*"); } -/** - * g_content_types_get_registered: - * - * Gets a list of strings containing the registered content types on - * the system. - * - * Returns: #GList of the registered content types. - **/ GList * g_content_types_get_registered (void) { @@ -428,6 +339,16 @@ _g_unix_content_type_get_parents (const char *type) return (char **)g_ptr_array_free (array, FALSE); } +/** + * g_content_type_equals: + * @type1: a content type string. + * @type2: a content type string. + * + * Compares two content types for equality. + * + * Returns: %TRUE if the two strings are identical or equivalent, + * %FALSE otherwise. + **/ gboolean g_content_type_equals (const char *type1, const char *type2) @@ -444,6 +365,16 @@ g_content_type_equals (const char *type1, return res; } +/** + * g_content_type_is_a: + * @type: a content type string. + * @supertype: a string. + * + * Determines if @type is a subset of @supertype. + * + * Returns: %TRUE if @type is a kind of @supertype, + * %FALSE otherwise. + **/ gboolean g_content_type_is_a (const char *type, const char *supertype) @@ -460,6 +391,14 @@ g_content_type_is_a (const char *type, return res; } +/** + * g_content_type_is_unknown: + * @type: a content type string. + * + * Checks if the content type is known by GIO. + * + * Returns: %TRUE if the type is unknown. + **/ gboolean g_content_type_is_unknown (const char *type) { @@ -624,6 +563,14 @@ load_comment_for_mime (const char *mimetype) return g_strdup_printf (_("%s type"), mimetype); } +/** + * g_content_type_get_description: + * @type: a content type string. + * + * Gets the human readable description of the content type. + * + * Returns: a short description of the content type @type. + **/ char * g_content_type_get_description (const char *type) { @@ -654,6 +601,14 @@ g_content_type_get_description (const char *type) return comment; } +/** + * g_content_type_get_mime_type: + * @type: a content type string. + * + * Gets the mime-type for the content type. + * + * Returns: the registered mime-type for the given @type. + **/ char * g_content_type_get_mime_type (const char *type) { @@ -662,6 +617,14 @@ g_content_type_get_mime_type (const char *type) return g_strdup (type); } +/** + * g_content_type_get_icon: + * @type: a content type string. + * + * Gets the icon for a content type. + * + * Returns: #GIcon corresponding to the content type. + **/ GIcon * g_content_type_get_icon (const char *type) { @@ -675,9 +638,11 @@ g_content_type_get_icon (const char *type) * g_content_type_can_be_executable: * @type: a content type string. * - * Returns: %TRUE if the file type corresponds to something that - * can be executable, %FALSE otherwise. Note that for instance - * things like textfiles can be executables (i.e. scripts) + * Checks if a content type can be executable. Note that for instance + * things like text files can be executables (i.e. scripts and batch files). + * + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. **/ gboolean g_content_type_can_be_executable (const char *type) @@ -703,6 +668,20 @@ looks_like_text (const guchar *data, gsize data_size) return TRUE; } +/** + * g_content_type_guess: + * @filename: a string. + * @data: a stream of data. + * @data_size: the size of @data. + * @result_uncertain: a flag indicating the certainty of the + * result. + * + * Guesses the content type based on example data. If the function is + * uncertain, @result_uncertain will be set to %TRUE. + * + * Returns: a string indicating a guessed content type for the + * given data. + **/ char * g_content_type_guess (const char *filename, const guchar *data, @@ -857,6 +836,14 @@ enumerate_mimetypes_dir (const char *dir, GHashTable *mimetypes) g_free (mimedir); } +/** + * g_content_types_get_registered: + * + * Gets a list of strings containing the registered content types on + * the system. + * + * Returns: #GList of the registered content types. + **/ GList * g_content_types_get_registered (void) { diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 7b3eed4..80c0a10 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -1336,11 +1336,13 @@ g_desktop_app_info_remove_supports_type (GAppInfo *appinfo, /** * g_app_info_create_from_commandline: - * @commandline: - * @application_name: - * @flags: - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. + * @commandline: the commandline to use + * @application_name: the application name, or %NULL to use @commandline + * @flags: flags that can specify details of the created #GAppInfo + * @error: a #GError location to store the error occuring, %NULL to ignore. + * + * Creates a new #GAppInfo from the given information. + * * Returns: new #GAppInfo for given command. **/ GAppInfo * @@ -1484,7 +1486,7 @@ app_info_in_list (GAppInfo *info, GList *l) /** * g_app_info_get_all_for_type: - * @content_type: + * @content_type: the content type to find a #GAppInfo for * * Gets a list of all #GAppInfo s for a given content type. * @@ -1523,12 +1525,11 @@ g_app_info_get_all_for_type (const char *content_type) /** * g_app_info_get_default_for_type: - * @content_type: - * @must_support_uris: + * @content_type: the content type to find a #GAppInfo for + * @must_support_uris: if %TRUE, the #GAppInfo is expected to + * support URIs * * Gets the #GAppInfo that correspond to a given content type. - * If @must_support_uris is true, the #GAppInfo is expected to - * support URIs. * * Returns: #GAppInfo for given @content_type. **/ diff --git a/gio/gdrive.c b/gio/gdrive.c index 26ec192..f902e04 100644 --- a/gio/gdrive.c +++ b/gio/gdrive.c @@ -105,9 +105,10 @@ g_drive_base_init (gpointer g_class) * g_drive_get_name: * @drive: a #GDrive. * - * Returns: string containing @drive's name. + * Gets the name of @drive. * - * The returned string should be freed when no longer needed. + * Returns: a string containing @drive's name. The returned + * string should be freed when no longer needed. **/ char * g_drive_get_name (GDrive *drive) diff --git a/gio/gfile.c b/gio/gfile.c index e925a4e..f5f8d5d 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -354,7 +354,7 @@ g_file_get_uri (GFile *file) } /** - * g_file_parse_name: + * g_file_get_parse_name: * @file: input #GFile. * * Gets the parsed name for the #GFile. @@ -943,7 +943,7 @@ g_file_find_enclosing_volume (GFile *file, * g_file_read: * @file: #GFile to read. * @cancellable: a #GCancellable - * @error: a #GError. + * @error: a #GError, or %NULL * * Reads a whole file into a #GFileInputStream. Fails returning %NULL if * given #GFile points to a directory. @@ -987,6 +987,7 @@ g_file_read (GFile *file, * @file: input #GFile. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * * If the #GFileIface for @file does not support appending to files, then * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. @@ -1028,7 +1029,7 @@ g_file_append_to (GFile *file, * @file: input #GFile. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, or %NULL * * If the #GFileIface for @file does not support creating files, then * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. @@ -1073,6 +1074,7 @@ g_file_create (GFile *file, * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * * If the #GFileIface for @file does not support streaming operations, then * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. @@ -1154,7 +1156,7 @@ g_file_read_async (GFile *file, * g_file_read_finish: * @file: input #GFile. * @res: a #GAsyncResult. - * @error: a #GError. + * @error: a #GError, or %NULL * * Finishes an asynchronous file read operation started with * g_file_read_async(). @@ -1232,7 +1234,7 @@ g_file_append_to_async (GFile *file, * g_file_append_to_finish: * @file: input #GFile. * @res: #GAsyncResult - * @error: a #GError. + * @error: a #GError, or #NULL * * Finishes appending to a file started with g_file_append_to_async(). * @@ -1301,7 +1303,7 @@ g_file_create_async (GFile *file, * g_file_create_finish: * @file: input #GFile. * @res: a #GAsyncResult. - * @error: a #GError. + * @error: a #GError, or %NULL * * Finishes creating a file started with g_file_create_async(). * @@ -1377,7 +1379,7 @@ g_file_replace_async (GFile *file, * g_file_replace_finish: * @file: input #GFile. * @res: a #GAsyncResult. - * @error: a #GError. + * @error: a #GError, or %NULL * * Finishes replacing the contents of the file started by * g_file_replace_async(). This is typically called within @@ -1811,7 +1813,7 @@ file_copy_fallback (GFile *source, * @cancellable: optional #GCancellable object, %NULL to ignore. * @progress_callback: function to callback with progress information * @progress_callback_data: userdata to pass to @progress_callback - * @error: #GError to set on error + * @error: #GError to set on error, or %NULL * * , - * or it can use #GThreads if available. g_simple_async_result_complete() will finish an - * I/O task directly within the main event loop. g_simple_async_result_complete_in_idle() will integrate - * the I/O task into the main event loop as an idle function and g_simple_async_result_run_in_thread() + * or it can use #GThreads if available. g_simple_async_result_complete() + * will finish an I/O task directly within the main event loop. + * g_simple_async_result_complete_in_idle() will integrate the I/O task into the + * main event loop as an idle function and g_simple_async_result_run_in_thread() * will run the job in a separate thread. * - * To set the results of an asynchronous function, g_simple_async_result_set_op_res_gpointer(), - * g_simple_async_result_set_op_res_gboolean(), and g_simple_async_result_set_op_res_gssize() - * are provided, setting the operation's result to a gpointer, gboolean, or gssize, respectively. - * - * Likewise, to get the result of an asynchronous function, g_simple_async_result_get_op_res_gpointer(), - * g_simple_async_result_get_op_res_gboolean(), and g_simple_async_result_get_op_res_gssize() are - * provided, getting the operation's result as a gpointer, gboolean, and gssize, respectively. - * + * To set the results of an asynchronous function, + * g_simple_async_result_set_op_res_gpointer(), + * g_simple_async_result_set_op_res_gboolean(), and + * g_simple_async_result_set_op_res_gssize() + * are provided, setting the operation's result to a gpointer, gboolean, or + * gssize, respectively. + * + * Likewise, to get the result of an asynchronous function, + * g_simple_async_result_get_op_res_gpointer(), + * g_simple_async_result_get_op_res_gboolean(), and + * g_simple_async_result_get_op_res_gssize() are + * provided, getting the operation's result as a gpointer, gboolean, and + * gssize, respectively. **/ static void g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface); diff --git a/gio/gunionvolumemonitor.c b/gio/gunionvolumemonitor.c index bc46d4c..10f9e31 100644 --- a/gio/gunionvolumemonitor.c +++ b/gio/gunionvolumemonitor.c @@ -340,7 +340,10 @@ g_union_volume_monitor_new (void) /** * g_volume_monitor_get: * - * Returns: a #GVolumeMonitor. + * Gets the volume monitor used by gio. + * + * Returns: a reference to the #GVolumeMonitor used by gio. Call + * g_object_unref() when done with it. **/ GVolumeMonitor * g_volume_monitor_get (void) @@ -349,7 +352,7 @@ g_volume_monitor_get (void) G_LOCK (the_volume_monitor); - if (the_volume_monitor ) + if (the_volume_monitor) vm = G_VOLUME_MONITOR (g_object_ref (the_volume_monitor)); else { -- 2.7.4