[gtksourceview/wip/loader-saver] File loading and saving: improve doc

[Sébastien Wilmet <swilmet src gnome org>]

commit d955ef4c864cc5ccf9aeeb7fbe9207cf2281715c
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Jul 8 22:00:08 2014 +0200

    File loading and saving: improve doc

 gtksourceview/gtksourcefile.c       |    9 +--------
 gtksourceview/gtksourcefileloader.c |   29 +++++++++++++++--------------
 gtksourceview/gtksourcefilesaver.c  |   35 +++++++++++++++++------------------
 3 files changed, 33 insertions(+), 40 deletions(-)
---
diff --git a/gtksourceview/gtksourcefile.c b/gtksourceview/gtksourcefile.c
index 08195ba..98b0415 100644
--- a/gtksourceview/gtksourcefile.c
+++ b/gtksourceview/gtksourcefile.c
@@ -246,14 +246,7 @@ gtk_source_file_new (void)
  * @file: a #GtkSourceFile.
  * @location: (nullable): the new #GFile, or %NULL.
  *
- * Sets the location. Most of the time it is better to change the location with a
- * #GtkSourceFileLoader or #GtkSourceFileSaver. By doing so, the location of
- * #GtkSourceFile is updated only when the file loading or saving have
- * succeeded.
- *
- * One use case of this function is when your application renames the file (with
- * g_file_move() for instance). In this case you don't want to reload the file
- * from the new location.
+ * Sets the location.
  *
  * Since: 3.14
  */
diff --git a/gtksourceview/gtksourcefileloader.c b/gtksourceview/gtksourcefileloader.c
index 0537985..be2c24f 100644
--- a/gtksourceview/gtksourcefileloader.c
+++ b/gtksourceview/gtksourcefileloader.c
@@ -36,8 +36,12 @@
  * @Title: GtkSourceFileLoader
  * @See_also: #GtkSourceFile, #GtkSourceFileSaver
  *
- * A #GtkSourceFileLoader object permits to load the content of a #GFile or a
+ * A #GtkSourceFileLoader object permits to load the contents of a #GFile or a
  * #GInputStream into a #GtkSourceBuffer.
+ *
+ * A file loader should be used only for one load operation, including errors
+ * handling. If an error occurs, you can reconfigure the loader and relaunch the
+ * operation with gtk_source_file_loader_load_async().
  */
 
 #if 0
@@ -302,7 +306,7 @@ gtk_source_file_loader_class_init (GtkSourceFileLoaderClass *klass)
         * GtkSourceFileLoader:buffer:
         *
         * The #GtkSourceBuffer to load the contents into. The
-        * #GtkSourceFileLoader object has a weak reference to the :buffer.
+        * #GtkSourceFileLoader object has a weak reference to the buffer.
         *
         * Since: 3.14
         */
@@ -319,7 +323,7 @@ gtk_source_file_loader_class_init (GtkSourceFileLoaderClass *klass)
         * GtkSourceFileLoader:file:
         *
         * The #GtkSourceFile. The #GtkSourceFileLoader object has a weak
-        * reference to the :file.
+        * reference to the file.
         *
         * Since: 3.14
         */
@@ -335,9 +339,9 @@ gtk_source_file_loader_class_init (GtkSourceFileLoaderClass *klass)
        /**
         * GtkSourceFileLoader:location:
         *
-        * The #GFile to load. If set to %NULL and if the
-        * #GtkSourceFileLoader:input-stream is %NULL too, the #GtkSourceFile's
-        * #GtkSourceFile:location is taken at construction time.
+        * The #GFile to load. If the #GtkSourceFileLoader:input-stream is
+        * %NULL, by default the location is taken from the #GtkSourceFile at
+        * construction time.
         *
         * Since: 3.14
         */
@@ -774,13 +778,10 @@ gtk_source_file_loader_error_quark (void)
  * @file: the #GtkSourceFile.
  *
  * Creates a new #GtkSourceFileLoader object. The contents is read from the
- * @file's #GtkSourceFile:location. If not already done, set the @file's
- * location with gtk_source_file_set_location() before calling this constructor.
- * The previous location is anyway not needed, because as soon as the file
- * loading begins, the @buffer is emptied.
- *
- * The file loader's #GtkSourceFileLoader:location is set at construction time
- * with the @file's #GtkSourceFile:location value.
+ * #GtkSourceFile's location. If not already done, call
+ * gtk_source_file_set_location() before calling this constructor. The previous
+ * location is anyway not needed, because as soon as the file loading begins,
+ * the @buffer is emptied.
  *
  * Returns: a new #GtkSourceFileLoader object.
  * Since: 3.14
@@ -834,7 +835,7 @@ gtk_source_file_loader_new_from_stream (GtkSourceBuffer *buffer,
  * Sets the candidate encodings for the file loading. The encodings are tried in
  * the same order as the list.
  *
- * There is by default only one candidate encoding, the #GtkSourceBuffer's
+ * There is by default only one candidate encoding, the #GtkSourceFile's
  * encoding.
  *
  * Since: 3.14
diff --git a/gtksourceview/gtksourcefilesaver.c b/gtksourceview/gtksourcefilesaver.c
index 222bde5..80262e1 100644
--- a/gtksourceview/gtksourcefilesaver.c
+++ b/gtksourceview/gtksourcefilesaver.c
@@ -39,6 +39,10 @@
  *
  * A #GtkSourceFileSaver object permits to save a #GtkSourceBuffer into a
  * #GFile.
+ *
+ * A file saver should be used only for one save operation, including errors
+ * handling. If an error occurs, you can reconfigure the saver and relaunch the
+ * operation with gtk_source_file_saver_save_async().
  */
 
 /* The code has been written initially in gedit (GeditDocumentSaver).
@@ -323,7 +327,7 @@ gtk_source_file_saver_class_init (GtkSourceFileSaverClass *klass)
         * GtkSourceFileSaver:buffer:
         *
         * The #GtkSourceBuffer to save. The #GtkSourceFileSaver object has a
-        * weak reference to the :buffer.
+        * weak reference to the buffer.
         *
         * Since: 3.14
         */
@@ -341,7 +345,7 @@ gtk_source_file_saver_class_init (GtkSourceFileSaverClass *klass)
         * GtkSourceFileSaver:file:
         *
         * The #GtkSourceFile. The #GtkSourceFileSaver object has a weak
-        * reference to the :file.
+        * reference to the file.
         *
         * Since: 3.14
         */
@@ -358,9 +362,8 @@ gtk_source_file_saver_class_init (GtkSourceFileSaverClass *klass)
        /**
         * GtkSourceFileSaver:location:
         *
-        * The #GFile where to save the buffer. If set to %NULL, the
-        * #GtkSourceFile's #GtkSourceFile:location is taken at construction
-        * time.
+        * The #GFile where to save the buffer. By default the location is taken
+        * from the #GtkSourceFile at construction time.
         *
         * Since: 3.14
         */
@@ -999,10 +1002,7 @@ gtk_source_file_saver_error_quark (void)
  * @file: the #GtkSourceFile.
  *
  * Creates a new #GtkSourceFileSaver object. The @buffer will be saved to the
- * @file's #GtkSourceFile:location.
- *
- * The file saver's #GtkSourceFileSaver:location is set at construction time
- * with the @file's #GtkSourceFile:location value.
+ * #GtkSourceFile's location.
  *
  * This constructor is suitable for a simple "save" operation, when the @file
  * already contains a non-%NULL #GtkSourceFile:location.
@@ -1034,8 +1034,8 @@ gtk_source_file_saver_new (GtkSourceBuffer *buffer,
  * #GtkSourceFile:location property. If an error occurs, the previous valid
  * location is still available in #GtkSourceFile.
  *
- * This constructor is suitable for a "save as" operation, or for saving for the
- * first time a new buffer.
+ * This constructor is suitable for a "save as" operation, or for saving a new
+ * buffer for the first time.
  *
  * Returns: a new #GtkSourceFileSaver object.
  * Since: 3.14
@@ -1106,10 +1106,8 @@ gtk_source_file_saver_get_location (GtkSourceFileSaver *saver)
  * @saver: a #GtkSourceFileSaver.
  * @encoding: (allow-none): the new encoding, or %NULL for UTF-8.
  *
- * Changes the #GtkSourceFileSaver:file encoding that will be used for the next
- * file saving. If @encoding is %NULL, the UTF-8 encoding will be set.
- *
- * Note that a #GtkSourceBuffer has always a UTF-8 encoding.
+ * Sets the encoding. If @encoding is %NULL, the UTF-8 encoding will be set.
+ * By default the encoding is taken from the #GtkSourceFile.
  *
  * Since: 3.14
  */
@@ -1152,7 +1150,8 @@ gtk_source_file_saver_get_encoding (GtkSourceFileSaver *saver)
  * @saver: a #GtkSourceFileSaver.
  * @newline_type: the new newline type.
  *
- * Changes the newline type that will be used for the next file saving.
+ * Sets the newline type. By default the newline type is taken from the
+ * #GtkSourceFile.
  *
  * Since: 3.14
  */
@@ -1190,8 +1189,8 @@ gtk_source_file_saver_get_newline_type (GtkSourceFileSaver *saver)
  * @saver: a #GtkSourceFileSaver.
  * @compression_type: the new compression type.
  *
- * Changes the #GtkSourceFileSaver:file compression type that will be used for
- * the next file saving.
+ * Sets the compression type. By default the compression type is taken from the
+ * #GtkSourceFile.
  *
  * Since: 3.14
  */