From 9f3f5f0905be71a34a2413f55f190423ebe0132a Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 16 Jul 2008 04:21:50 +0000 Subject: [PATCH] Small documentation fixes svn path=/trunk/; revision=7187 --- gio/ChangeLog | 4 ++++ gio/gfile.c | 44 ++++++++++++++++++++++++++++---------------- 2 files changed, 32 insertions(+), 16 deletions(-) diff --git a/gio/ChangeLog b/gio/ChangeLog index 876ff02..d33e3c1 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,7 @@ +2008-07-16 Matthias Clasen + + * gfile.c: Small documentation fixes. + 2008-07-15 Matthias Clasen * gunixmounts.c: Use g_strcmp0 instead of rolling our own. diff --git a/gio/gfile.c b/gio/gfile.c index ec8c58a..e26a222 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -1306,6 +1306,7 @@ g_file_find_enclosing_mount (GFile *file, return (* iface->find_enclosing_mount) (file, cancellable, error); } + /** * g_file_find_enclosing_mount_async: * @file: a #GFile @@ -5056,20 +5057,23 @@ g_file_query_default_handler (GFile *file, * @file: input #GFile. * @cancellable: optional #GCancellable object, %NULL to ignore. * @contents: a location to place the contents of the file. - * @length: a location to place the length of the contents of the file. - * @etag_out: a location to place the current entity tag for the file. + * @length: a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * - * Loads the content of the file into memory, returning the size of - * the data. The data is always zero terminated, but this is not - * included in the resultant @length. + * Loads the content of the file into memory. The data is always + * zero-terminated, but this is not included in the resultant @length. + * The returned @content should be freed with g_free() when no longer + * needed. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * Returns: %TRUE if the @file's contents were successfully loaded. - * %FALSE if there were errors.. + * %FALSE if there were errors. **/ gboolean g_file_load_contents (GFile *file, @@ -5361,12 +5365,17 @@ g_file_load_partial_contents_async (GFile *file, * @file: input #GFile. * @res: a #GAsyncResult. * @contents: a location to place the contents of the file. - * @length: a location to place the length of the contents of the file. - * @etag_out: a location to place the current entity tag for the file. + * @length: a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous partial load operation that was started - * with g_file_load_partial_contents_async(). + * with g_file_load_partial_contents_async(). The data is always + * zero-terminated, but this is not included in the resultant @length. + * The returned @content should be freed with g_free() when no longer + * needed. * * Returns: %TRUE if the load was successful. If %FALSE and @error is * present, it will be set appropriately. @@ -5462,13 +5471,16 @@ g_file_load_contents_async (GFile *file, * @file: input #GFile. * @res: a #GAsyncResult. * @contents: a location to place the contents of the file. - * @length: a location to place the length of the contents of the file. - * @etag_out: a location to place the current entity tag for the file. + * @length: a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous load of the @file's contents. * The contents are placed in @contents, and @length is set to the - * size of the @contents string. If @etag_out is present, it will be + * size of the @contents string. The @content should be freed with + * g_free() when no longer needed. If @etag_out is present, it will be * set to the new entity tag for the @file. * * Returns: %TRUE if the load was successful. If %FALSE and @error is @@ -5496,12 +5508,12 @@ g_file_load_contents_finish (GFile *file, * @contents: a string containing the new contents for @file. * @length: the length of @contents in bytes. * @etag: the old entity tag - * for the document. + * for the document, or %NULL * @make_backup: %TRUE if a backup should be created. * @flags: a set of #GFileCreateFlags. * @new_etag: a location to a new entity tag * for the document. This should be freed with g_free() when no longer - * needed. + * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL * @@ -5709,7 +5721,7 @@ replace_contents_open_callback (GObject *obj, * @file: input #GFile. * @contents: string of contents to replace the file with. * @length: the length of @contents in bytes. - * @etag: a new entity tag for the @file. + * @etag: a new entity tag 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. @@ -5774,7 +5786,7 @@ g_file_replace_contents_async (GFile *file, * @res: a #GAsyncResult. * @new_etag: a location of a new entity tag * for the document. This should be freed with g_free() when it is no - * longer needed. + * longer needed, or %NULL * @error: a #GError, or %NULL * * Finishes an asynchronous replace of the given @file. See -- 2.7.4