[gtksourceview] docs: improve doc of GtkSourceView and GtkSourceBuffer

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

commit bb31468bca603110944226deddb2ad03c95c62dd
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Nov 22 18:28:33 2014 +0100

    docs: improve doc of GtkSourceView and GtkSourceBuffer

 docs/reference/gtksourceview-3.0-sections.txt |   22 ++++++++--------
 gtksourceview/gtksourcebuffer.c               |   34 +++++++++++++-----------
 gtksourceview/gtksourceview.c                 |   31 ++++++++++++++--------
 3 files changed, 49 insertions(+), 38 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index a5317e5..5cb1219 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -753,35 +753,35 @@ GtkSourceDrawSpacesFlags
 GtkSourceViewGutterPosition
 gtk_source_view_new
 gtk_source_view_new_with_buffer
+gtk_source_view_set_show_line_numbers
+gtk_source_view_get_show_line_numbers
+gtk_source_view_set_show_right_margin
+gtk_source_view_get_show_right_margin
+gtk_source_view_set_right_margin_position
+gtk_source_view_get_right_margin_position
+gtk_source_view_set_highlight_current_line
+gtk_source_view_get_highlight_current_line
 gtk_source_view_set_auto_indent
 gtk_source_view_get_auto_indent
 gtk_source_view_set_indent_on_tab
 gtk_source_view_get_indent_on_tab
 gtk_source_view_set_indent_width
 gtk_source_view_get_indent_width
+gtk_source_view_set_tab_width
+gtk_source_view_get_tab_width
 gtk_source_view_set_insert_spaces_instead_of_tabs
 gtk_source_view_get_insert_spaces_instead_of_tabs
+gtk_source_view_get_visual_column
 gtk_source_view_set_smart_home_end
 gtk_source_view_get_smart_home_end
 gtk_source_view_set_mark_attributes
 gtk_source_view_get_mark_attributes
-gtk_source_view_set_highlight_current_line
-gtk_source_view_get_highlight_current_line
 gtk_source_view_set_show_line_marks
 gtk_source_view_get_show_line_marks
-gtk_source_view_set_show_line_numbers
-gtk_source_view_get_show_line_numbers
-gtk_source_view_set_show_right_margin
-gtk_source_view_get_show_right_margin
-gtk_source_view_set_right_margin_position
-gtk_source_view_get_right_margin_position
-gtk_source_view_set_tab_width
-gtk_source_view_get_tab_width
 gtk_source_view_set_draw_spaces
 gtk_source_view_get_draw_spaces
 gtk_source_view_get_completion
 gtk_source_view_get_gutter
-gtk_source_view_get_visual_column
 <SUBSECTION Standard>
 GtkSourceViewClass
 GTK_SOURCE_IS_VIEW
diff --git a/gtksourceview/gtksourcebuffer.c b/gtksourceview/gtksourcebuffer.c
index 2b55820..1fd4d01 100644
--- a/gtksourceview/gtksourcebuffer.c
+++ b/gtksourceview/gtksourcebuffer.c
@@ -47,35 +47,37 @@
 
 /**
  * SECTION:buffer
- * @Short_description: Buffer object for GtkSourceView
+ * @Short_description: Stores the text for display in a GtkSourceView
  * @Title: GtkSourceBuffer
  * @See_also: #GtkTextBuffer, #GtkSourceView
  *
- * The #GtkSourceBuffer object is the model for #GtkSourceView widgets.
- * It extends the #GtkTextBuffer object by adding features useful to display
+ * A #GtkSourceBuffer object is the model for #GtkSourceView widgets.
+ * It extends the #GtkTextBuffer class by adding features useful to display
  * and edit source code such as syntax highlighting and bracket matching. It
- * also implements support for undo/redo operations, and for the search and
- * replace.
+ * also implements support for the undo/redo.
  *
  * To create a #GtkSourceBuffer use gtk_source_buffer_new() or
  * gtk_source_buffer_new_with_language(). The second form is just a convenience
- * function which allows you to initially set a #GtkSourceLanguage.
+ * function which allows you to initially set a #GtkSourceLanguage. You can also
+ * directly create a #GtkSourceView and get its #GtkSourceBuffer with
+ * gtk_text_view_get_buffer().
  *
- * By default highlighting is enabled, but you can disable it with
+ * The highlighting is enabled by default, but you can disable it with
  * gtk_source_buffer_set_highlight_syntax().
  *
- * # Undo and Redo
+ * # Undo/Redo
  *
  * A custom #GtkSourceUndoManager can be implemented and set with
  * gtk_source_buffer_set_undo_manager(). However the default implementation
- * should be suitable for most uses. By default, actions that can be undone or
- * redone are defined as groups of operations between a call to
- * gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action(). In
- * general, this happens whenever the user presses any key which modifies the
- * buffer. But the default undo manager will try to merge similar consecutive
- * actions into one undo/redo level. The merging is done word by word, so after
- * writing a new sentence (character by character), each undo will remove the
- * previous word.
+ * should be suitable for most uses, so you can use the API provided by
+ * #GtkSourceBuffer instead of using #GtkSourceUndoManager. By default, actions
+ * that can be undone or redone are defined as groups of operations between a
+ * call to gtk_text_buffer_begin_user_action() and
+ * gtk_text_buffer_end_user_action(). In general, this happens whenever the user
+ * presses any key which modifies the buffer. But the default undo manager will
+ * try to merge similar consecutive actions into one undo/redo level. The
+ * merging is done word by word, so after writing a new sentence (character by
+ * character), each undo will remove the previous word.
  *
  * The default undo manager remembers the "modified" state of the buffer, and
  * restores it when an action is undone or redone. It can be useful in a text
diff --git a/gtksourceview/gtksourceview.c b/gtksourceview/gtksourceview.c
index a2c9856..49052eb 100644
--- a/gtksourceview/gtksourceview.c
+++ b/gtksourceview/gtksourceview.c
@@ -49,13 +49,22 @@
 
 /**
  * SECTION:view
- * @Short_description: The view object
+ * @Short_description: Widget that displays a GtkSourceBuffer
  * @Title: GtkSourceView
  * @See_also: #GtkTextView, #GtkSourceBuffer
  *
- * #GtkSourceView is the main object of the GtkSourceView library. It provides
- * a text view with syntax highlighting, undo/redo and text marks. Use a
- * #GtkSourceBuffer to display text with a #GtkSourceView.
+ * #GtkSourceView is the main class of the GtkSourceView library.
+ * Use a #GtkSourceBuffer to display text with a #GtkSourceView.
+ *
+ * This class provides:
+ *  - Show the line numbers;
+ *  - Show a right margin;
+ *  - Highlight the current line;
+ *  - 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.
  *
  * # GtkSourceView as GtkBuildable
  *
@@ -2561,12 +2570,12 @@ gtk_source_view_create_buffer (GtkTextView *text_view)
 /**
  * gtk_source_view_new:
  *
- * Creates a new #GtkSourceView. An empty default buffer will be
- * created for you. If you want to specify your own buffer, consider
- * gtk_source_view_new_with_buffer().
+ * Creates a new #GtkSourceView. An empty default #GtkSourceBuffer will be
+ * created for you and can be retrieved with gtk_text_view_get_buffer(). If you
+ * want to specify your own buffer, consider gtk_source_view_new_with_buffer().
  *
- * Return value: a new #GtkSourceView.
- **/
+ * Returns: a new #GtkSourceView.
+ */
 GtkWidget *
 gtk_source_view_new (void)
 {
@@ -2586,8 +2595,8 @@ gtk_source_view_new (void)
  * Creates a new #GtkSourceView widget displaying the buffer
  * @buffer. One buffer can be shared among many widgets.
  *
- * Return value: a new #GtkSourceView.
- **/
+ * Returns: a new #GtkSourceView.
+ */
 GtkWidget *
 gtk_source_view_new_with_buffer (GtkSourceBuffer *buffer)
 {