[gtksourceview/wip/loader-saver: 1/2] Move documentation to the FileSaver.

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

commit ad140155bab5f17e1beb1403385b0fe4ad284ca8
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Mar 25 18:42:49 2014 +0100

    Move documentation to the FileSaver.

 docs/reference/gtksourceview-3.0-sections.txt |   55 ++++-------
 docs/reference/gtksourceview-docs.xml         |    2 +-
 gtksourceview/gtksourcefile.c                 |  120 -------------------------
 gtksourceview/gtksourcefilesaver.c            |   38 ++++++++
 4 files changed, 59 insertions(+), 156 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index 2418c41..ce4ec35 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -6,6 +6,10 @@
 GtkSourceBuffer
 GtkSourceBracketMatchType
 GtkSourceChangeCaseType
+GtkSourceNewlineType
+GTK_SOURCE_NEWLINE_TYPE_DEFAULT
+GtkSourceCompressionType
+GtkSourceMountOperationFactory
 gtk_source_buffer_new
 gtk_source_buffer_new_with_language
 gtk_source_buffer_set_highlight_syntax
@@ -226,42 +230,23 @@ gtk_source_encoding_get_type
 </SECTION>
 
 <SECTION>
-<FILE>file</FILE>
-<TITLE>GtkSourceFile</TITLE>
-GtkSourceFile
-GtkSourceNewlineType
-GtkSourceCompressionType
-GtkSourceFileSaveFlags
-GtkSourceMountOperationFactory
-GTK_SOURCE_FILE_ERROR
-<SUBSECTION>
-gtk_source_file_new
-gtk_source_file_get_location
-gtk_source_file_get_buffer
-gtk_source_file_get_encoding
-gtk_source_file_set_encoding
-gtk_source_file_get_newline_type
-gtk_source_file_set_newline_type
-gtk_source_file_get_compression_type
-gtk_source_file_set_compression_type
-gtk_source_file_get_ensure_trailing_newline
-gtk_source_file_set_ensure_trailing_newline
-gtk_source_file_set_mount_operation_factory
-gtk_source_file_load_async
-gtk_source_file_load_finish
-gtk_source_file_save_async
-gtk_source_file_save_finish
+<FILE>filesaver</FILE>
+<TITLE>GtkSourceFileSaver</TITLE>
+GtkSourceFileSaver
+gtk_source_file_saver_new
+gtk_source_file_saver_save_async
+gtk_source_file_saver_save_finish
+gtk_source_file_saver_set_mount_operation_factory
 <SUBSECTION Standard>
-GTK_SOURCE_FILE
-GTK_SOURCE_FILE_CLASS
-GTK_SOURCE_FILE_GET_CLASS
-GTK_SOURCE_IS_FILE
-GTK_SOURCE_IS_FILE_CLASS
-GTK_SOURCE_TYPE_FILE
-GtkSourceFileClass
-GtkSourceFilePrivate
-gtk_source_file_error_quark
-gtk_source_file_get_type
+GTK_SOURCE_FILE_SAVER
+GTK_SOURCE_FILE_SAVER_CLASS
+GTK_SOURCE_FILE_SAVER_GET_CLASS
+GTK_SOURCE_IS_FILE_SAVER
+GTK_SOURCE_IS_FILE_SAVER_CLASS
+GTK_SOURCE_TYPE_FILE_SAVER
+GtkSourceFileSaverClass
+GtkSourceFileSaverPrivate
+gtk_source_file_saver_get_type
 </SECTION>
 
 <SECTION>
diff --git a/docs/reference/gtksourceview-docs.xml b/docs/reference/gtksourceview-docs.xml
index 6dc1d31..3d67a15 100644
--- a/docs/reference/gtksourceview-docs.xml
+++ b/docs/reference/gtksourceview-docs.xml
@@ -25,7 +25,7 @@
     <xi:include href="xml/completionprovider.xml"/>
     <xi:include href="xml/completionwords.xml"/>
     <xi:include href="xml/encoding.xml"/>
-    <xi:include href="xml/file.xml"/>
+    <xi:include href="xml/filesaver.xml"/>
     <xi:include href="xml/gutter.xml"/>
     <xi:include href="xml/gutterrenderer.xml"/>
     <xi:include href="xml/gutterrendererpixbuf.xml"/>
diff --git a/gtksourceview/gtksourcefile.c b/gtksourceview/gtksourcefile.c
index 143d9ec..5809fc0 100644
--- a/gtksourceview/gtksourcefile.c
+++ b/gtksourceview/gtksourcefile.c
@@ -595,123 +595,3 @@ gtk_source_file_load_finish (GtkSourceFile  *file,
 
        return ok;
 }
-
-#if 0
-/**
- * gtk_source_file_save_async:
- * @file: a #GtkSourceFile.
- * @flags: a set of #GtkSourceFileSaveFlags.
- * @io_priority: the I/O priority of the request. E.g. %G_PRIORITY_LOW,
- *   %G_PRIORITY_DEFAULT or %G_PRIORITY_HIGH.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @progress_callback: (allow-none): function to call back with progress
- *   information, or %NULL if progress information is not needed.
- * @progress_callback_data: user data to pass to @progress_callback.
- * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
- *   satisfied.
- * @user_data: user data to pass to @callback.
- *
- * Saves asynchronously the #GtkSourceFile:buffer into the
- * #GtkSourceFile:location. See the #GAsyncResult documentation to know how to
- * use this function.
- *
- * Since: 3.14
- */
-void
-gtk_source_file_save_async (GtkSourceFile          *file,
-                           GtkSourceFileSaveFlags  flags,
-                           gint                    io_priority,
-                           GCancellable           *cancellable,
-                           GFileProgressCallback   progress_callback,
-                           gpointer                progress_callback_data,
-                           GAsyncReadyCallback     callback,
-                           gpointer                user_data)
-{
-       GTimeVal *mtime;
-
-       g_return_if_fail (GTK_SOURCE_IS_FILE (file));
-
-       if (file->priv->saver != NULL)
-       {
-               g_task_report_new_error (file,
-                                        callback,
-                                        user_data,
-                                        file,
-                                        G_IO_ERROR,
-                                        G_IO_ERROR_PENDING,
-                                        "Another save operation is already running on the file \"%s\".",
-                                        g_file_get_parse_name (file->priv->location));
-
-               return;
-       }
-
-       if (file->priv->mtime_set)
-       {
-               mtime = &file->priv->mtime;
-       }
-       else
-       {
-               mtime = NULL;
-               flags |= GTK_SOURCE_FILE_SAVE_IGNORE_MTIME;
-       }
-
-       file->priv->saver = gtk_source_file_saver_new (file,
-                                                      file->priv->encoding,
-                                                      file->priv->newline_type,
-                                                      file->priv->compression_type,
-                                                      file->priv->ensure_trailing_newline,
-                                                      flags);
-
-       gtk_source_file_saver_save_async (file->priv->saver,
-                                         mtime,
-                                         io_priority,
-                                         cancellable,
-                                         progress_callback,
-                                         progress_callback_data,
-                                         callback,
-                                         user_data);
-}
-
-/**
- * gtk_source_file_save_finish:
- * @file: a #GtkSourceFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL.
- *
- * Finishes a file saving started with gtk_source_file_save_async().
- *
- * Returns: whether the file was saved successfully.
- * Since: 3.14
- */
-gboolean
-gtk_source_file_save_finish (GtkSourceFile  *file,
-                            GAsyncResult   *result,
-                            GError        **error)
-{
-       gboolean ok;
-
-       g_return_val_if_fail (GTK_SOURCE_IS_FILE (file), FALSE);
-       g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
-
-       if (g_async_result_is_tagged (result, file))
-       {
-               return g_task_propagate_boolean (G_TASK (result), error);
-       }
-
-       g_return_val_if_fail (file->priv->saver != NULL, FALSE);
-
-       ok = gtk_source_file_saver_save_finish (file->priv->saver, result, error);
-
-       if (ok)
-       {
-               GFileInfo *info = gtk_source_file_saver_get_info (file->priv->saver);
-
-               g_file_info_get_modification_time (info, &file->priv->mtime);
-               file->priv->mtime_set = TRUE;
-       }
-
-       g_clear_object (&file->priv->saver);
-
-       return ok;
-}
-#endif
diff --git a/gtksourceview/gtksourcefilesaver.c b/gtksourceview/gtksourcefilesaver.c
index e789159..498bfc5 100644
--- a/gtksourceview/gtksourcefilesaver.c
+++ b/gtksourceview/gtksourcefilesaver.c
@@ -811,6 +811,14 @@ recover_not_mounted (GtkSourceFileSaver *saver)
        g_object_unref (mount_operation);
 }
 
+/**
+ * gtk_source_file_saver_new:
+ * @buffer: the #GtkSourceBuffer to save.
+ * @file: the #GFile where to save the @buffer to.
+ *
+ * Returns: a new #GtkSourceFileSaver object.
+ * Since: 3.14
+ */
 GtkSourceFileSaver *
 gtk_source_file_saver_new (GtkSourceBuffer *buffer,
                           GFile           *file)
@@ -824,6 +832,25 @@ gtk_source_file_saver_new (GtkSourceBuffer *buffer,
                             NULL);
 }
 
+/**
+ * gtk_source_file_saver_save_async:
+ * @saver: a #GtkSourceFileSaver.
+ * @io_priority: the I/O priority of the request. E.g. %G_PRIORITY_LOW,
+ *   %G_PRIORITY_DEFAULT or %G_PRIORITY_HIGH.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @progress_callback: (allow-none): function to call back with progress
+ *   information, or %NULL if progress information is not needed.
+ * @progress_callback_data: (closure): user data to pass to @progress_callback.
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
+ *   satisfied.
+ * @user_data: user data to pass to @callback.
+ *
+ * Saves asynchronously the #GtkSourceFileSaver:buffer into the
+ * #GtkSourceFileSaver:file. See the #GAsyncResult documentation to know how to
+ * use this function.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_file_saver_save_async (GtkSourceFileSaver     *saver,
                                  gint                    io_priority,
@@ -849,6 +876,17 @@ gtk_source_file_saver_save_async (GtkSourceFileSaver     *saver,
        begin_write (saver);
 }
 
+/**
+ * gtk_source_file_saver_save_finish:
+ * @saver: a #GtkSourceFileSaver.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL.
+ *
+ * Finishes a file saving started with gtk_source_file_saver_save_async().
+ *
+ * Returns: whether the file was saved successfully.
+ * Since: 3.14
+ */
 gboolean
 gtk_source_file_saver_save_finish (GtkSourceFileSaver  *saver,
                                   GAsyncResult        *result,