[gtksourceview/wip/loader-saver: 10/23] GtkSourceEncoding documentation

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

commit a4481e0645bc70db5cacdc14b4d6f7f3555834f6
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Wed Jun 4 19:00:25 2014 +0200

    GtkSourceEncoding documentation

 docs/reference/gtksourceview-3.0-sections.txt |    4 +-
 gtksourceview/gtksourceencoding.c             |  100 +++++++++++++++++++++++--
 2 files changed, 94 insertions(+), 10 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index e7c2952..c66745f 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -222,13 +222,13 @@ gtk_source_completion_words_get_type
 <TITLE>GtkSourceEncoding</TITLE>
 GtkSourceEncoding
 <SUBSECTION>
+gtk_source_encoding_get_utf8
+gtk_source_encoding_get_current
 gtk_source_encoding_get_from_charset
 gtk_source_encoding_get_from_index
 gtk_source_encoding_to_string
 gtk_source_encoding_get_name
 gtk_source_encoding_get_charset
-gtk_source_encoding_get_utf8
-gtk_source_encoding_get_current
 gtk_source_encoding_copy
 gtk_source_encoding_free
 <SUBSECTION Standard>
diff --git a/gtksourceview/gtksourceencoding.c b/gtksourceview/gtksourceencoding.c
index 9a01706..c84c81a 100644
--- a/gtksourceview/gtksourceencoding.c
+++ b/gtksourceview/gtksourceencoding.c
@@ -23,6 +23,17 @@
 #include "gtksourceencoding.h"
 #include "gtksourceview-i18n.h"
 
+/**
+ * SECTION:encoding
+ * @Short_description: Character encoding
+ * @Title: GtkSourceEncoding
+ * @See_also: #GtkSourceFileSaver, #GtkSourceFileLoader
+ *
+ * The #GtkSourceEncoding boxed type represents a character encoding. It is used
+ * for example by the #GtkSourceFileSaver and #GtkSourceFileLoader. Note that
+ * the text in GTK+ widgets is always encoded in UTF-8.
+ */
+
 struct _GtkSourceEncoding
 {
        gint index;
@@ -287,6 +298,16 @@ gtk_source_encoding_lazy_init (void)
        initialized = TRUE;
 }
 
+/**
+ * gtk_source_encoding_get_from_charset:
+ * @charset: a character set.
+ *
+ * Gets a #GtkSourceEncoding from a character set such as "UTF-8" or
+ * "ISO-8859-1".
+ *
+ * Returns: the corresponding #GtkSourceEncoding, or %NULL if not found.
+ * Since: 3.14
+ */
 const GtkSourceEncoding *
 gtk_source_encoding_get_from_charset (const gchar *charset)
 {
@@ -318,25 +339,49 @@ gtk_source_encoding_get_from_charset (const gchar *charset)
        return NULL;
 }
 
+/**
+ * gtk_source_encoding_get_from_index:
+ * @index: the index.
+ *
+ * Gets the #GtkSourceEncoding located at @index. The first valid index is 0.
+ * This function can be used in a loop that stops when %NULL is returned.
+ *
+ * Returns: the #GtkSourceEncoding at @index, or %NULL.
+ * Since: 3.14
+ */
 const GtkSourceEncoding *
-gtk_source_encoding_get_from_index (gint idx)
+gtk_source_encoding_get_from_index (gint index)
 {
-       g_return_val_if_fail (idx >= 0, NULL);
+       g_return_val_if_fail (index >= 0, NULL);
 
-       if (idx >= GTK_SOURCE_ENCODING_LAST)
+       if (index >= GTK_SOURCE_ENCODING_LAST)
        {
                return NULL;
        }
 
-       return &encodings[idx];
+       return &encodings[index];
 }
 
+/**
+ * gtk_source_encoding_get_utf8:
+ *
+ * Returns: the UTF-8 encoding.
+ * Since: 3.14
+ */
 const GtkSourceEncoding *
 gtk_source_encoding_get_utf8 (void)
 {
        return &utf8_encoding;
 }
 
+/**
+ * gtk_source_encoding_get_current:
+ *
+ * Gets the #GtkSourceEncoding for the current locale. See also g_get_charset().
+ *
+ * Returns: the current locale encoding.
+ * Since: 3.14
+ */
 const GtkSourceEncoding *
 gtk_source_encoding_get_current (void)
 {
@@ -371,6 +416,13 @@ gtk_source_encoding_get_current (void)
        return locale_encoding;
 }
 
+/**
+ * gtk_source_encoding_to_string:
+ * @enc: a #GtkSourceEncoding.
+ *
+ * Returns: a string representation. Free with g_free() when no longer needed.
+ * Since: 3.14
+ */
 gchar *
 gtk_source_encoding_to_string (const GtkSourceEncoding* enc)
 {
@@ -394,6 +446,16 @@ gtk_source_encoding_to_string (const GtkSourceEncoding* enc)
        }
 }
 
+/**
+ * gtk_source_encoding_get_charset:
+ * @enc: a #GtkSourceEncoding.
+ *
+ * Gets the character set of the #GtkSourceEncoding, such as "UTF-8" or
+ * "ISO-8859-1".
+ *
+ * Returns: the character set of the #GtkSourceEncoding.
+ * Since: 3.14
+ */
 const gchar *
 gtk_source_encoding_get_charset (const GtkSourceEncoding* enc)
 {
@@ -406,6 +468,15 @@ gtk_source_encoding_get_charset (const GtkSourceEncoding* enc)
        return enc->charset;
 }
 
+/**
+ * gtk_source_encoding_get_name:
+ * @enc: a #GtkSourceEncoding.
+ *
+ * Gets the name of the #GtkSourceEncoding such as "Unicode" or "Western".
+ *
+ * Returns: the name of the #GtkSourceEncoding.
+ * Since: 3.14
+ */
 const gchar *
 gtk_source_encoding_get_name (const GtkSourceEncoding* enc)
 {
@@ -416,10 +487,15 @@ gtk_source_encoding_get_name (const GtkSourceEncoding* enc)
        return (enc->name == NULL) ? _("Unknown") : _(enc->name);
 }
 
-/* These are to make language bindings happy. Since Encodings are
- * const, copy() just returns the same pointer and free() does
- * nothing. */
-
+/**
+ * gtk_source_encoding_copy:
+ * @enc: a #GtkSourceEncoding.
+ *
+ * Used by language bindings.
+ *
+ * Returns: a copy of @enc.
+ * Since: 3.14
+ */
 GtkSourceEncoding *
 gtk_source_encoding_copy (const GtkSourceEncoding *enc)
 {
@@ -428,6 +504,14 @@ gtk_source_encoding_copy (const GtkSourceEncoding *enc)
        return (GtkSourceEncoding *) enc;
 }
 
+/**
+ * gtk_source_encoding_free:
+ * @enc: a #GtkSourceEncoding.
+ *
+ * Used by language bindings.
+ *
+ * Since: 3.14
+ */
 void
 gtk_source_encoding_free (GtkSourceEncoding *enc)
 {