[gtksourceview: 3/3] docs: improve doc of StyleScheme and applying it to a buffer

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

commit 514ade7978b140ed2153d12d8cb5fccbaada179a
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Jun 19 14:02:48 2016 +0200

    docs: improve doc of StyleScheme and applying it to a buffer

 gtksourceview/gtksourcebuffer.c      |   17 ++++++++++++++---
 gtksourceview/gtksourcestylescheme.c |    6 +++++-
 2 files changed, 19 insertions(+), 4 deletions(-)
---
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index 4145800..794f79a 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -1863,9 +1863,20 @@ gtk_source_buffer_ensure_highlight (GtkSourceBuffer   *buffer,
  * @buffer: a #GtkSourceBuffer.
  * @scheme: (nullable): a #GtkSourceStyleScheme or %NULL.
  *
- * Sets style scheme used by the buffer. If @scheme is %NULL no
- * style scheme is used.
- **/
+ * Sets a #GtkSourceStyleScheme to be used by the buffer and the view.
+ *
+ * Note that a #GtkSourceStyleScheme affects not only the syntax highlighting,
+ * but also other #GtkSourceView features such as highlighting the current line,
+ * matching brackets, the line numbers, etc.
+ *
+ * Instead of setting a %NULL @scheme, it is better to disable syntax
+ * highlighting with gtk_source_buffer_set_highlight_syntax(), and setting the
+ * #GtkSourceStyleScheme with the "classic" or "tango" ID, because those two
+ * style schemes follow more closely the GTK+ theme (for example for the
+ * background color).
+ *
+ * The buffer holds a reference to @scheme.
+ */
 void
 gtk_source_buffer_set_style_scheme (GtkSourceBuffer      *buffer,
                                    GtkSourceStyleScheme *scheme)
diff --git a/gtksourceview/gtksourcestylescheme.c b/gtksourceview/gtksourcestylescheme.c
index 9a307fb..cbb1f53 100644
--- a/gtksourceview/gtksourcestylescheme.c
+++ b/gtksourceview/gtksourcestylescheme.c
@@ -42,10 +42,14 @@
  * #GtkSourceStyleScheme contains all the text styles to be used in
  * #GtkSourceView and #GtkSourceBuffer. For instance, it contains text styles
  * for syntax highlighting, it may contain foreground and background color for
- * non-highlighted text, color for the line numbers, etc.
+ * non-highlighted text, color for the line numbers, current line highlighting,
+ * bracket matching, etc.
  *
  * Style schemes are stored in XML files. The format of a scheme file is
  * documented in the [style scheme reference][style-reference].
+ *
+ * The two style schemes with IDs "classic" and "tango" follow more closely the
+ * GTK+ theme (for example for the background color).
  */
 
 #define STYLE_TEXT                     "text"