[gtksourceview/wip/loader-saver] Document some of the GtkSourceFile API

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

commit c6936910cb2819857db39cab6da0763194abcd63
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Dec 28 22:09:29 2013 +0100

    Document some of the GtkSourceFile API

 gtksourceview/gtksourcefile.c |  106 +++++++++++++++++++++++++++++++++++++++-
 gtksourceview/gtksourcefile.h |   13 ++++--
 2 files changed, 112 insertions(+), 7 deletions(-)
---
diff --git a/gtksourceview/gtksourcefile.c b/gtksourceview/gtksourcefile.c
index 0e01bd2..847a7f1 100644
--- a/gtksourceview/gtksourcefile.c
+++ b/gtksourceview/gtksourcefile.c
@@ -227,7 +227,7 @@ gtk_source_file_class_init (GtkSourceFileClass *klass)
        g_object_class_install_property (object_class, PROP_ENSURE_TRAILING_NEWLINE,
                                         g_param_spec_boolean ("ensure-trailing-newline",
                                                               "Ensure trailing newline",
-                                                              "Ensure the buffer ends with a trailing 
newline",
+                                                              "Ensure the file ends with a trailing newline",
                                                               TRUE,
                                                               G_PARAM_READWRITE |
                                                               G_PARAM_CONSTRUCT |
@@ -253,6 +253,14 @@ gtk_source_file_error_quark (void)
        return quark;
 }
 
+/**
+ * gtk_source_file_new:
+ * @location: a #GFile.
+ * @buffer: a #GtkSourceBuffer.
+ *
+ * Returns: a new #GtkSourceFile object.
+ * Since: 3.14
+ */
 GtkSourceFile *
 gtk_source_file_new (GFile           *location,
                     GtkSourceBuffer *buffer)
@@ -266,6 +274,14 @@ gtk_source_file_new (GFile           *location,
                             NULL);
 }
 
+/**
+ * gtk_source_file_get_location:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: (transfer full): the location. Call g_object_unref() on the return
+ * value when no longer needed.
+ * Since: 3.14
+ */
 GFile *
 gtk_source_file_get_location (GtkSourceFile *file)
 {
@@ -274,6 +290,13 @@ gtk_source_file_get_location (GtkSourceFile *file)
        return g_object_ref (file->priv->location);
 }
 
+/**
+ * gtk_source_file_get_buffer:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: (transfer none): the buffer.
+ * Since: 3.14
+ */
 GtkSourceBuffer *
 gtk_source_file_get_buffer (GtkSourceFile *file)
 {
@@ -282,6 +305,13 @@ gtk_source_file_get_buffer (GtkSourceFile *file)
        return file->priv->buffer;
 }
 
+/**
+ * gtk_source_file_get_encoding:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: the encoding.
+ * Since: 3.14
+ */
 const GtkSourceEncoding *
 gtk_source_file_get_encoding (GtkSourceFile *file)
 {
@@ -290,6 +320,16 @@ gtk_source_file_get_encoding (GtkSourceFile *file)
        return file->priv->encoding;
 }
 
+/**
+ * gtk_source_file_set_encoding:
+ * @file: a #GtkSourceFile.
+ * @encoding: the new encoding.
+ *
+ * Changes the encoding used for file loading and saving. Note that the
+ * #GtkSourceBuffer has always a UTF-8 encoding.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_file_set_encoding (GtkSourceFile           *file,
                              const GtkSourceEncoding *encoding)
@@ -303,6 +343,13 @@ gtk_source_file_set_encoding (GtkSourceFile           *file,
        }
 }
 
+/**
+ * gtk_source_file_get_newline_type:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: the newline type.
+ * Since: 3.14
+ */
 GtkSourceNewlineType
 gtk_source_file_get_newline_type (GtkSourceFile *file)
 {
@@ -311,9 +358,19 @@ gtk_source_file_get_newline_type (GtkSourceFile *file)
        return file->priv->newline_type;
 }
 
+/**
+ * gtk_source_file_set_newline_type:
+ * @file: a #GtkSourceFile.
+ * @newline_type: the new newline type.
+ *
+ * Changes the newline type used for the file loading and saving. It doesn't
+ * change the newline type of the #GtkSourceBuffer.
+ *
+ * Since: 3.14
+ */
 void
-gtk_source_file_set_newline_type (GtkSourceFile *file,
-                                 GtkSourceNewlineType newline_type)
+gtk_source_file_set_newline_type (GtkSourceFile        *file,
+                                 GtkSourceNewlineType  newline_type)
 {
        g_return_if_fail (GTK_SOURCE_IS_FILE (file));
 
@@ -324,6 +381,13 @@ gtk_source_file_set_newline_type (GtkSourceFile *file,
        }
 }
 
+/**
+ * gtk_source_file_get_compression_type:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: the compression type.
+ * Since: 3.14
+ */
 GtkSourceCompressionType
 gtk_source_file_get_compression_type (GtkSourceFile *file)
 {
@@ -332,6 +396,16 @@ gtk_source_file_get_compression_type (GtkSourceFile *file)
        return file->priv->compression_type;
 }
 
+/**
+ * gtk_source_file_set_compression_type:
+ * @file: a #GtkSourceFile.
+ * @compression_type: the new compression type.
+ *
+ * Changes the compression type used for the file loading and saving. It doesn't
+ * affect the #GtkSourceBuffer.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_file_set_compression_type (GtkSourceFile            *file,
                                      GtkSourceCompressionType  compression_type)
@@ -345,6 +419,13 @@ gtk_source_file_set_compression_type (GtkSourceFile            *file,
        }
 }
 
+/**
+ * gtk_source_file_get_ensure_trailing_newline:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: whether the file should end with a trailing newline.
+ * Since: 3.14
+ */
 gboolean
 gtk_source_file_get_ensure_trailing_newline (GtkSourceFile *file)
 {
@@ -353,6 +434,25 @@ gtk_source_file_get_ensure_trailing_newline (GtkSourceFile *file)
        return file->priv->ensure_trailing_newline;
 }
 
+/**
+ * gtk_source_file_set_ensure_trailing_newline:
+ * @file: a #GtkSourceFile.
+ * @ensure_trailing_newline: whether the file should end with a trailing
+ * newline.
+ *
+ * If a #GtkTextBuffer contains a trailing newline, there will be one more
+ * visible line in a #GtkTextView. This is generally not what the user expects.
+ *
+ * When @ensure_trailing_newline is %TRUE, the trailing newline (if present) is
+ * removed when the file is loaded into the #GtkTextBuffer. When the buffer is
+ * saved into the file, a trailing newline is always added.
+ *
+ * On the other hand, when @ensure_trailing_newline is %FALSE, the file's
+ * contents is not modified when loaded into the buffer, and the buffer's
+ * contents is not modified when saved into the file.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_file_set_ensure_trailing_newline (GtkSourceFile *file,
                                             gboolean       ensure_trailing_newline)
diff --git a/gtksourceview/gtksourcefile.h b/gtksourceview/gtksourcefile.h
index 2545bcb..74b9e6c 100644
--- a/gtksourceview/gtksourcefile.h
+++ b/gtksourceview/gtksourcefile.h
@@ -55,7 +55,7 @@ typedef enum
  * @GTK_SOURCE_COMPRESSION_TYPE_NONE: save file in plain text.
  * @GTK_SOURCE_COMPRESSION_TYPE_GZIP: save file using gzip compression.
  *
- * Since: 3.12
+ * Since: 3.14
  */
 typedef enum
 {
@@ -71,7 +71,7 @@ typedef enum
  *
  * FIXME ignore invalid chars is not yet used in gsv
  *
- * Since: 3.12
+ * Since: 3.14
  */
 typedef enum
 {
@@ -93,8 +93,13 @@ enum
 };
 
 /**
- * GtkSourceMountOperationFactory: (skip)
- * @userdata:
+ * GtkSourceMountOperationFactory:
+ * @userdata: user data
+ *
+ * Type definition for a function that will be called to create a
+ * #GMountOperation. This is useful for creating a #GtkMountOperation.
+ *
+ * Since: 3.14
  */
 typedef GMountOperation *(*GtkSourceMountOperationFactory)(gpointer userdata);