[gtksourceview] docs: improve doc of GtkSourceLanguage and applying it to a buffer

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

commit bc64e1b1a48ee56943be4e501f37a39a97b26834
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Jun 19 13:05:52 2016 +0200

    docs: improve doc of GtkSourceLanguage and applying it to a buffer
    
    https://bugzilla.gnome.org/show_bug.cgi?id=760984#c15

 gtksourceview/gtksourcebuffer.c   |   12 ++++++------
 gtksourceview/gtksourcelanguage.c |    9 +++++----
 2 files changed, 11 insertions(+), 10 deletions(-)
---
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index 9190479..d802133 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -96,7 +96,7 @@
  * undo's effect). Warning: the selection restoring behavior might change in the
  * future.
  *
- * # Context Classes
+ * # Context Classes # {#context-classes}
  *
  * It is possible to retrieve some information from the syntax highlighting
  * engine. The default context classes that are applied to regions of a
@@ -1722,11 +1722,11 @@ gtk_source_buffer_set_highlight_syntax (GtkSourceBuffer *buffer,
  * @buffer: a #GtkSourceBuffer.
  * @language: (nullable): a #GtkSourceLanguage to set, or %NULL.
  *
- * Associate a #GtkSourceLanguage with the buffer. If @language is
- * not-%NULL and syntax highlighting is enabled (see gtk_source_buffer_set_highlight_syntax()),
- * the syntax patterns defined in @language will be used to highlight the text
- * contained in the buffer. If @language is %NULL, the text contained in the
- * buffer is not highlighted.
+ * Associates a #GtkSourceLanguage with the buffer.
+ *
+ * Note that a #GtkSourceLanguage affects not only the syntax highlighting, but
+ * also the [context classes][context-classes]. If you want to disable just the
+ * syntax highlighting, see gtk_source_buffer_set_highlight_syntax().
  *
  * The buffer holds a reference to @language.
  */
diff --git a/gtksourceview/gtksourcelanguage.c b/gtksourceview/gtksourcelanguage.c
index a374acd..dbb51dd 100644
--- a/gtksourceview/gtksourcelanguage.c
+++ b/gtksourceview/gtksourcelanguage.c
@@ -46,10 +46,11 @@
  * @Title: GtkSourceLanguage
  * @See_also: #GtkSourceLanguageManager
  *
- * #GtkSourceLanguage encapsulates syntax and highlighting styles for a
- * particular language. Use #GtkSourceLanguageManager to obtain a
- * #GtkSourceLanguage instance, and gtk_source_buffer_set_language() to apply it
- * to a #GtkSourceBuffer.
+ * A #GtkSourceLanguage represents a programming or markup language, affecting
+ * syntax highlighting and [context classes][context-classes].
+ *
+ * Use #GtkSourceLanguageManager to obtain a #GtkSourceLanguage instance, and
+ * gtk_source_buffer_set_language() to apply it to a #GtkSourceBuffer.
  */
 
 #define DEFAULT_SECTION _("Others")