[gtksourceview/wip/encodings: 1/3] Better document gtk_source_encoding_get_default_candidates()

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

commit cc1c6628f7c32b7734d51106fbb915d10d046b80
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Aug 10 16:36:27 2014 +0200

    Better document gtk_source_encoding_get_default_candidates()

 docs/reference/gtksourceview-3.0-sections.txt |    1 +
 gtksourceview/gtksourceencoding.c             |    8 +++++++-
 gtksourceview/gtksourcefileloader.c           |    5 +++--
 3 files changed, 11 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index fe3c0b4..acd010c 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -222,6 +222,7 @@ gtk_source_encoding_to_string
 gtk_source_encoding_get_name
 gtk_source_encoding_get_charset
 gtk_source_encoding_foreach
+gtk_source_encoding_get_default_candidates
 gtk_source_encoding_copy
 gtk_source_encoding_free
 <SUBSECTION Standard>
diff --git a/gtksourceview/gtksourceencoding.c b/gtksourceview/gtksourceencoding.c
index 8644602..c8a2ba9 100644
--- a/gtksourceview/gtksourceencoding.c
+++ b/gtksourceview/gtksourceencoding.c
@@ -490,8 +490,14 @@ gtk_source_encoding_get_name (const GtkSourceEncoding* enc)
 /**
  * gtk_source_encoding_get_default_candidates:
  *
+ * Gets the list of default candidate encodings to try when loading a file. See
+ * gtk_source_file_loader_set_candidate_encodings().
+ *
+ * This function returns a different list depending on the current locale (i.e.
+ * language, country and default encoding).
+ *
  * Returns: (transfer container) (element-type GtkSource.Encoding): the list of
- * default candidates encodings. Free with g_slist_free().
+ * default candidate encodings. Free with g_slist_free().
  */
 GSList *
 gtk_source_encoding_get_default_candidates (void)
diff --git a/gtksourceview/gtksourcefileloader.c b/gtksourceview/gtksourcefileloader.c
index f297a9e..a2524c7 100644
--- a/gtksourceview/gtksourcefileloader.c
+++ b/gtksourceview/gtksourcefileloader.c
@@ -874,8 +874,9 @@ 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 #GtkSourceFile's
- * encoding.
+ * By default the candidate encodings are (in that order):
+ * 1. If set, the #GtkSourceFile's encoding. See gtk_source_file_get_encoding().
+ * 2. The list returned by gtk_source_encoding_get_default_candidates().
  *
  * Since: 3.14
  */