[gtksourceview/wip/new-space-drawing-api] docs: update docs related to white space drawing

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

commit 1451e235dea96bd772fe90b4739e2da8364da3eb
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Sep 25 18:20:33 2016 +0200

    docs: update docs related to white space drawing

 docs/reference/gtksourceview-3.0-sections.txt |    4 +-
 gtksourceview/gtksourcespacedrawer.c          |   35 +++++++++++++++++++++---
 gtksourceview/gtksourcespacedrawer.h          |   16 +++++-----
 gtksourceview/gtksourcetag.c                  |    4 +-
 gtksourceview/gtksourceview.c                 |    1 -
 5 files changed, 42 insertions(+), 18 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index 5cca889..8dc7dc2 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -745,10 +745,10 @@ gtk_source_search_settings_get_type
 GtkSourceSpaceDrawer
 GtkSourceSpaceTypeFlags
 GtkSourceSpaceLocationFlags
-gtk_source_space_drawer_get_types_for_locations
 gtk_source_space_drawer_set_types_for_locations
-gtk_source_space_drawer_get_matrix
+gtk_source_space_drawer_get_types_for_locations
 gtk_source_space_drawer_set_matrix
+gtk_source_space_drawer_get_matrix
 <SUBSECTION Standard>
 GTK_SOURCE_IS_SPACE_DRAWER
 GTK_SOURCE_IS_SPACE_DRAWER_CLASS
diff --git a/gtksourceview/gtksourcespacedrawer.c b/gtksourceview/gtksourcespacedrawer.c
index c39ec3c..dd531d3 100644
--- a/gtksourceview/gtksourcespacedrawer.c
+++ b/gtksourceview/gtksourcespacedrawer.c
@@ -33,9 +33,34 @@
 
 /**
  * SECTION:spacedrawer
- * @Short_description: Represent whitespace characters with symbols
+ * @Short_description: Represent white space characters with symbols
  * @Title: GtkSourceSpaceDrawer
  * @See_also: #GtkSourceView
+ *
+ * #GtkSourceSpaceDrawer provides a way to visualize white spaces, by drawing
+ * symbols.
+ *
+ * By default, no white spaces are drawn. To draw white spaces,
+ * gtk_source_space_drawer_set_types_for_locations() can be called to set the
+ * #GtkSourceSpaceDrawer:matrix property.
+ *
+ * For a finer-grained method, there is also the GtkSourceTag's
+ * #GtkSourceTag:draw-spaces property.
+ *
+ * # Example
+ *
+ * To draw non-breaking spaces everywhere and draw all types of trailing spaces
+ * except newlines:
+ * |[
+ * gtk_source_space_drawer_set_types_for_locations (space_drawer,
+ *                                                  GTK_SOURCE_SPACE_LOCATION_ALL,
+ *                                                  GTK_SOURCE_SPACE_TYPE_NBSP);
+ *
+ * gtk_source_space_drawer_set_types_for_locations (space_drawer,
+ *                                                  GTK_SOURCE_SPACE_LOCATION_TRAILING,
+ *                                                  GTK_SOURCE_SPACE_TYPE_ALL &
+ *                                                  ~GTK_SOURCE_SPACE_TYPE_NEWLINE);
+ * ]|
  */
 
 /* A drawer specially designed for the International Space Station. It comes by
@@ -248,7 +273,7 @@ gtk_source_space_drawer_class_init (GtkSourceSpaceDrawerClass *klass)
         * GtkSourceSpaceDrawer:matrix:
         *
         * The :matrix property is a #GVariant property to specify where and
-        * what kind of whitespaces to draw.
+        * what kind of white spaces to draw.
         *
         * The #GVariant is of type `"au"`, an array of unsigned integers. Each
         * integer is a combination of #GtkSourceSpaceTypeFlags. There is one
@@ -438,12 +463,12 @@ _gtk_source_space_drawer_set_flags (GtkSourceSpaceDrawer     *drawer,
  * @locations: one or several #GtkSourceSpaceLocationFlags.
  *
  * If only one location is specified, this function returns what kind of
- * whitespaces are drawn at that location. The value is retrieved from the
+ * white spaces are drawn at that location. The value is retrieved from the
  * #GtkSourceSpaceDrawer:matrix property.
  *
  * If several locations are specified, this function returns the logical AND for
- * those locations. Which means that if a certain kind of whitespace is present
- * in the return value, then that kind of whitespace is drawn at all the
+ * those locations. Which means that if a certain kind of white space is present
+ * in the return value, then that kind of white space is drawn at all the
  * specified @locations.
  *
  * Returns: a combination of #GtkSourceSpaceTypeFlags.
diff --git a/gtksourceview/gtksourcespacedrawer.h b/gtksourceview/gtksourcespacedrawer.h
index e18f68f..be99fff 100644
--- a/gtksourceview/gtksourcespacedrawer.h
+++ b/gtksourceview/gtksourcespacedrawer.h
@@ -66,9 +66,9 @@ struct _GtkSourceSpaceDrawerClass
  * @GTK_SOURCE_SPACE_TYPE_TAB: Tab character.
  * @GTK_SOURCE_SPACE_TYPE_NEWLINE: Line break character.
  * @GTK_SOURCE_SPACE_TYPE_NBSP: Non-breaking space character.
- * @GTK_SOURCE_SPACE_TYPE_ALL: All whitespaces.
+ * @GTK_SOURCE_SPACE_TYPE_ALL: All white spaces.
  *
- * #GtkSourceSpaceTypeFlags contains flags for whitespace types.
+ * #GtkSourceSpaceTypeFlags contains flags for white space types.
  *
  * Since: 3.24
  */
@@ -85,15 +85,15 @@ typedef enum _GtkSourceSpaceTypeFlags
 /**
  * GtkSourceSpaceLocationFlags:
  * @GTK_SOURCE_SPACE_LOCATION_NONE: No flags.
- * @GTK_SOURCE_SPACE_LOCATION_LEADING: Leading whitespaces on a line, i.e. the
+ * @GTK_SOURCE_SPACE_LOCATION_LEADING: Leading white spaces on a line, i.e. the
  *   indentation.
- * @GTK_SOURCE_SPACE_LOCATION_INSIDE_TEXT: Whitespaces inside a line of text.
- * @GTK_SOURCE_SPACE_LOCATION_TRAILING: Trailing whitespaces on a line.
- * @GTK_SOURCE_SPACE_LOCATION_ALL: Whitespaces anywhere.
+ * @GTK_SOURCE_SPACE_LOCATION_INSIDE_TEXT: White spaces inside a line of text.
+ * @GTK_SOURCE_SPACE_LOCATION_TRAILING: Trailing white spaces on a line.
+ * @GTK_SOURCE_SPACE_LOCATION_ALL: White spaces anywhere.
  *
- * #GtkSourceSpaceLocationFlags contains flags for whitespace locations.
+ * #GtkSourceSpaceLocationFlags contains flags for white space locations.
  *
- * If a line contains only whitespaces (no text), the whitespaces match both
+ * If a line contains only white spaces (no text), the white spaces match both
  * %GTK_SOURCE_SPACE_LOCATION_LEADING and %GTK_SOURCE_SPACE_LOCATION_TRAILING.
  *
  * Since: 3.24
diff --git a/gtksourceview/gtksourcetag.c b/gtksourceview/gtksourcetag.c
index ab6c796..7031e13 100644
--- a/gtksourceview/gtksourcetag.c
+++ b/gtksourceview/gtksourcetag.c
@@ -127,8 +127,8 @@ gtk_source_tag_class_init (GtkSourceTagClass *klass)
        /**
         * GtkSourceTag:draw-spaces:
         *
-        * Whether to draw spaces. This property takes precedence over the value
-        * defined by the GtkSourceView's #GtkSourceView:draw-spaces property
+        * Whether to draw white spaces. This property takes precedence over the value
+        * defined by the GtkSourceSpaceDrawer's #GtkSourceSpaceDrawer:matrix property
         * (only where the tag is applied).
         *
         * Setting this property also changes #GtkSourceTag:draw-spaces-set to
diff --git a/gtksourceview/gtksourceview.c b/gtksourceview/gtksourceview.c
index 5fcb8dd..7a897a9 100644
--- a/gtksourceview/gtksourceview.c
+++ b/gtksourceview/gtksourceview.c
@@ -69,7 +69,6 @@
  *  - Indentation settings;
  *  - Configuration for the Home and End keyboard keys;
  *  - Configure and show line marks;
- *  - A way to visualize white spaces (by drawing symbols);
  *  - And a few other things.
  *
  * An easy way to test all these features is to use the test-widget mini-program