[gtksourceview/wip/loader-saver] FileLoader documentation

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

commit b998b81cf5b02c9aa7fb1a9ae8f3d4f206ef6831
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Mar 28 18:03:50 2014 +0100

    FileLoader documentation

 docs/reference/Makefile.am                    |    1 -
 docs/reference/gtksourceview-3.0-sections.txt |   26 ++++++++-
 docs/reference/gtksourceview-docs.xml         |    1 +
 gtksourceview/gtksourcefileloader.c           |   78 +++++++++++++++++++++++++
 4 files changed, 104 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 06afa8e..effba76 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -33,7 +33,6 @@ IGNORE_HFILES =                                       \
        gtksourcecompletionwordsutils.h         \
        gtksourcecontextengine.h                \
        gtksourceengine.h                       \
-       gtksourcefileloader.h                   \
        gtksourcegutter-private.h               \
        gtksourcegutterrendererlines.h          \
        gtksourcegutterrenderermarks.h          \
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index ce4ec35..cf6e1df 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -230,13 +230,37 @@ gtk_source_encoding_get_type
 </SECTION>
 
 <SECTION>
+<FILE>fileloader</FILE>
+<TITLE>GtkSourceFileLoader</TITLE>
+GtkSourceFileLoader
+gtk_source_file_loader_new
+gtk_source_file_loader_new_from_stream
+gtk_source_file_loader_set_candidate_encodings
+gtk_source_file_loader_set_mount_operation_factory
+gtk_source_file_loader_load_async
+gtk_source_file_loader_load_finish
+gtk_source_file_loader_get_encoding
+gtk_source_file_loader_get_newline_type
+gtk_source_file_loader_get_compression_type
+<SUBSECTION Standard>
+GTK_SOURCE_FILE_LOADER
+GTK_SOURCE_FILE_LOADER_CLASS
+GTK_SOURCE_FILE_LOADER_GET_CLASS
+GTK_SOURCE_IS_FILE_LOADER
+GTK_SOURCE_IS_FILE_LOADER_CLASS
+GTK_SOURCE_TYPE_FILE_LOADER
+GtkSourceFileLoaderPrivate
+gtk_source_file_loader_get_type
+</SECTION>
+
+<SECTION>
 <FILE>filesaver</FILE>
 <TITLE>GtkSourceFileSaver</TITLE>
 GtkSourceFileSaver
 gtk_source_file_saver_new
+gtk_source_file_saver_set_mount_operation_factory
 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_SAVER
 GTK_SOURCE_FILE_SAVER_CLASS
diff --git a/docs/reference/gtksourceview-docs.xml b/docs/reference/gtksourceview-docs.xml
index 3d67a15..6de50f4 100644
--- a/docs/reference/gtksourceview-docs.xml
+++ b/docs/reference/gtksourceview-docs.xml
@@ -25,6 +25,7 @@
     <xi:include href="xml/completionprovider.xml"/>
     <xi:include href="xml/completionwords.xml"/>
     <xi:include href="xml/encoding.xml"/>
+    <xi:include href="xml/fileloader.xml"/>
     <xi:include href="xml/filesaver.xml"/>
     <xi:include href="xml/gutter.xml"/>
     <xi:include href="xml/gutterrenderer.xml"/>
diff --git a/gtksourceview/gtksourcefileloader.c b/gtksourceview/gtksourcefileloader.c
index 970d1a4..b4ccf40 100644
--- a/gtksourceview/gtksourcefileloader.c
+++ b/gtksourceview/gtksourcefileloader.c
@@ -679,6 +679,14 @@ open_file (GtkSourceFileLoader *loader)
                           loader);
 }
 
+/**
+ * gtk_source_file_loader_new:
+ * @buffer: the output #GtkSourceBuffer.
+ * @file: the #GFile to load.
+ *
+ * Returns: a new #GtkSourceFileLoader object.
+ * Since: 3.14
+ */
 GtkSourceFileLoader *
 gtk_source_file_loader_new (GtkSourceBuffer *buffer,
                            GFile           *file)
@@ -692,6 +700,14 @@ gtk_source_file_loader_new (GtkSourceBuffer *buffer,
                             NULL);
 }
 
+/**
+ * gtk_source_file_loader_new_from_stream:
+ * @buffer: the output #GtkSourceBuffer.
+ * @stream: the #GInputStream to load, e.g. stdin.
+ *
+ * Returns: a new #GtkSourceFileLoader object.
+ * Since: 3.14
+ */
 GtkSourceFileLoader *
 gtk_source_file_loader_new_from_stream (GtkSourceBuffer *buffer,
                                        GInputStream    *stream)
@@ -705,15 +721,45 @@ gtk_source_file_loader_new_from_stream (GtkSourceBuffer *buffer,
                             NULL);
 }
 
+/**
+ * gtk_source_file_loader_set_candidate_encodings:
+ * @loader: a #GtkSourceFileLoader.
+ * @candidate_encodings: a %NULL-terminated list of #GtkSourceEncoding<!-- -->s.
+ *
+ * Sets the candidate encodings for the file loading. The encodings are tried in
+ * the same order as the list.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_file_loader_set_candidate_encodings (GtkSourceFileLoader *loader,
                                                GSList              *candidate_encodings)
 {
        g_return_if_fail (loader->priv->candidate_encodings == NULL);
 
+       g_slist_free (loader->priv->candidate_encodings);
        loader->priv->candidate_encodings = g_slist_copy (candidate_encodings);
 }
 
+/**
+ * gtk_source_file_loader_load_async:
+ * @loader: a #GtkSourceFileLoader.
+ * @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.
+ *
+ * Loads asynchronously the #GtkSourceFileLoader:file into the
+ * #GtkSourceFileLoader:buffer. See the #GAsyncResult documentation to know how to
+ * use this function.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_file_loader_load_async (GtkSourceFileLoader   *loader,
                                   gint                   io_priority,
@@ -749,6 +795,17 @@ gtk_source_file_loader_load_async (GtkSourceFileLoader   *loader,
        }
 }
 
+/**
+ * gtk_source_file_loader_load_finish:
+ * @loader: a #GtkSourceFileLoader.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL.
+ *
+ * Finishes a file loading started with gtk_source_file_loader_load_async().
+ *
+ * Returns: whether the file was loaded successfully.
+ * Since: 3.14
+ */
 gboolean
 gtk_source_file_loader_load_finish (GtkSourceFileLoader  *loader,
                                    GAsyncResult         *result,
@@ -767,6 +824,13 @@ gtk_source_file_loader_load_finish (GtkSourceFileLoader  *loader,
        return ok;
 }
 
+/**
+ * gtk_source_file_loader_get_encoding:
+ * @loader: a #GtkSourceFileLoader.
+ *
+ * Returns: the detected file encoding.
+ * Since: 3.14
+ */
 const GtkSourceEncoding *
 gtk_source_file_loader_get_encoding (GtkSourceFileLoader *loader)
 {
@@ -783,6 +847,13 @@ gtk_source_file_loader_get_encoding (GtkSourceFileLoader *loader)
        return loader->priv->auto_detected_encoding;
 }
 
+/**
+ * gtk_source_file_loader_get_newline_type:
+ * @loader: a #GtkSourceFileLoader.
+ *
+ * Returns: the detected newline type.
+ * Since: 3.14
+ */
 GtkSourceNewlineType
 gtk_source_file_loader_get_newline_type (GtkSourceFileLoader *loader)
 {
@@ -792,6 +863,13 @@ gtk_source_file_loader_get_newline_type (GtkSourceFileLoader *loader)
        return loader->priv->auto_detected_newline_type;
 }
 
+/**
+ * gtk_source_file_loader_get_compression_type:
+ * @loader: a #GtkSourceFileLoader.
+ *
+ * Returns: the detected compression type.
+ * Since: 3.14
+ */
 GtkSourceCompressionType
 gtk_source_file_loader_get_compression_type (GtkSourceFileLoader *loader)
 {