Move documentation to inline comments: GtkTextBuffer

4 files changed, 45 insertions, 974 deletions

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 35d3e2ae27..8c3a63d506 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -113,6 +113,7 @@ gtkstyle.sgml
 gtktable.sgml
 gtktearoffmenuitem.sgml
 gtktesting.sgml
+gtktextbuffer.sgml
 gtktextiter.sgml
 gtktextmark.sgml
 gtktexttag.sgml
diff --git a/docs/reference/gtk/tmpl/gtktextbuffer.sgml b/docs/reference/gtk/tmpl/gtktextbuffer.sgml
deleted file mode 100644
index ff1c01a417..0000000000
--- a/docs/reference/gtk/tmpl/gtktextbuffer.sgml
+++ /dev/null
@@ -1,974 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkTextBuffer
-
-<!-- ##### SECTION Short_Description ##### -->
-Stores attributed text for display in a GtkTextView
-
-<!-- ##### SECTION Long_Description ##### -->
-
-<para>
-You may wish to begin by reading the <link linkend="TextWidget">text widget
-conceptual overview</link> which gives an overview of all the objects and data
-types related to the text widget and how they work together.
-</para>
-
-<para>
-
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkTextView, #GtkTextIter, #GtkTextMark
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkTextBuffer ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SIGNAL GtkTextBuffer::apply-tag ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-@arg3: 
-
-<!-- ##### SIGNAL GtkTextBuffer::begin-user-action ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-
-<!-- ##### SIGNAL GtkTextBuffer::changed ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-
-<!-- ##### SIGNAL GtkTextBuffer::delete-range ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-
-<!-- ##### SIGNAL GtkTextBuffer::end-user-action ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-
-<!-- ##### SIGNAL GtkTextBuffer::insert-child-anchor ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-
-<!-- ##### SIGNAL GtkTextBuffer::insert-pixbuf ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-
-<!-- ##### SIGNAL GtkTextBuffer::insert-text ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-@arg3: 
-
-<!-- ##### SIGNAL GtkTextBuffer::mark-deleted ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkTextBuffer::mark-set ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-
-<!-- ##### SIGNAL GtkTextBuffer::modified-changed ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-
-<!-- ##### SIGNAL GtkTextBuffer::paste-done ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkTextBuffer::remove-tag ##### -->
-<para>
-
-</para>
-
-@textbuffer: the object which received the signal.
-@arg1: 
-@arg2: 
-@arg3: 
-
-<!-- ##### ARG GtkTextBuffer:copy-target-list ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkTextBuffer:cursor-position ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkTextBuffer:has-selection ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkTextBuffer:paste-target-list ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkTextBuffer:tag-table ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkTextBuffer:text ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_text_buffer_new ##### -->
-<para>
-
-</para>
-
-@table: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_line_count ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_char_count ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_tag_table ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@text: 
-@len: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_at_cursor ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@text: 
-@len: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_interactive ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@text: 
-@len: 
-@default_editable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_interactive_at_cursor ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@text: 
-@len: 
-@default_editable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_range ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_range_interactive ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@start: 
-@end: 
-@default_editable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_with_tags ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@text: 
-@len: 
-@first_tag: 
-@Varargs: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_with_tags_by_name ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@text: 
-@len: 
-@first_tag_name: 
-@Varargs: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_delete ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_delete_interactive ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start_iter: 
-@end_iter: 
-@default_editable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_backspace ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@interactive: 
-@default_editable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_set_text ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@text: 
-@len: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_text ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start: 
-@end: 
-@include_hidden_chars: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_slice ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start: 
-@end: 
-@include_hidden_chars: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_pixbuf ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@pixbuf: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_insert_child_anchor ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@anchor: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_create_child_anchor ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_create_mark ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@mark_name: 
-@where: 
-@left_gravity: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_move_mark ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@mark: 
-@where: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_move_mark_by_name ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@name: 
-@where: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_add_mark ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@mark: 
-@where: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_delete_mark ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@mark: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_delete_mark_by_name ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@name: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_mark ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_insert ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_selection_bound ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_has_selection ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_place_cursor ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@where: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_select_range ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@ins: 
-@bound: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_apply_tag ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@tag: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_remove_tag ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@tag: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_apply_tag_by_name ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@name: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_remove_tag_by_name ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@name: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_remove_all_tags ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_create_tag ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@tag_name: 
-@first_property_name: 
-@Varargs: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_iter_at_line_offset ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@line_number: 
-@char_offset: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_iter_at_offset ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@char_offset: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_iter_at_line ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@line_number: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_iter_at_line_index ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@line_number: 
-@byte_index: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_iter_at_mark ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@mark: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_iter_at_child_anchor ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-@anchor: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_start_iter ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_end_iter ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@iter: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_bounds ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start: 
-@end: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_modified ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_set_modified ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@setting: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_delete_selection ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@interactive: 
-@default_editable: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_paste_clipboard ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@clipboard: 
-@override_location: 
-@default_editable: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_copy_clipboard ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@clipboard: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_cut_clipboard ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@clipboard: 
-@default_editable: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_selection_bounds ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@start: 
-@end: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_begin_user_action ##### -->
-<para>
-
-</para>
-
-@buffer: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_end_user_action ##### -->
-<para>
-
-</para>
-
-@buffer: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_add_selection_clipboard ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@clipboard: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_remove_selection_clipboard ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@clipboard: 
-
-
-<!-- ##### ENUM GtkTextBufferTargetInfo ##### -->
-<para>
-
-</para>
-
-@GTK_TEXT_BUFFER_TARGET_INFO_BUFFER_CONTENTS: 
-@GTK_TEXT_BUFFER_TARGET_INFO_RICH_TEXT: 
-@GTK_TEXT_BUFFER_TARGET_INFO_TEXT: 
-
-<!-- ##### USER_FUNCTION GtkTextBufferDeserializeFunc ##### -->
-<para>
-A function that is called to deserialize rich text that has been
-serialized with gtk_text_buffer_serialize(), and insert it at @iter.
-</para>
-
-@register_buffer: the #GtkTextBuffer the format is registered with
-@content_buffer: the #GtkTextBuffer to deserialize into
-@iter: insertion point for the deserialized text
-@data: data to deserialize
-@length: length of %data
-@create_tags: %TRUE if deserializing may create tags
-@user_data: user data that was specified when registering the format
-@error: return location for a #GError
-@Returns: %TRUE on success, %FALSE otherwise
-
-
-<!-- ##### FUNCTION gtk_text_buffer_deserialize ##### -->
-<para>
-
-</para>
-
-@register_buffer: 
-@content_buffer: 
-@format: 
-@iter: 
-@data: 
-@length: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_deserialize_get_can_create_tags ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@format: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_deserialize_set_can_create_tags ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@format: 
-@can_create_tags: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_copy_target_list ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_deserialize_formats ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@n_formats: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_paste_target_list ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_get_serialize_formats ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@n_formats: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_register_deserialize_format ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@mime_type: 
-@function: 
-@user_data: 
-@user_data_destroy: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_register_deserialize_tagset ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@tagset_name: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_register_serialize_format ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@mime_type: 
-@function: 
-@user_data: 
-@user_data_destroy: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_register_serialize_tagset ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@tagset_name: 
-@Returns: 
-
-
-<!-- ##### USER_FUNCTION GtkTextBufferSerializeFunc ##### -->
-<para>
-A function that is called to serialize the content of a text buffer.
-It must return the serialized form of the content.
-</para>
-
-@register_buffer: the #GtkTextBuffer for which the format is registered
-@content_buffer: the #GtkTextBuffer to serialize
-@start: start of the block of text to serialize
-@end: end of the block of text to serialize
-@length: Return location for the length of the serialized data
-@user_data: user data that was specified when registering the format
-@Returns: a newly-allocated array of guint8 which contains the serialized
-          data, or %NULL if an error occurred
-
-
-<!-- ##### FUNCTION gtk_text_buffer_serialize ##### -->
-<para>
-
-</para>
-
-@register_buffer: 
-@content_buffer: 
-@format: 
-@start: 
-@end: 
-@length: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_unregister_deserialize_format ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@format: 
-
-
-<!-- ##### FUNCTION gtk_text_buffer_unregister_serialize_format ##### -->
-<para>
-
-</para>
-
-@buffer: 
-@format: 
-
-
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index a576c69aa6..24ca6e18e9 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -43,6 +43,18 @@
 #include "gtkintl.h"
 
 
+/**
+ * SECTION:gtktextbuffer
+ * @Short_description: Stores attributed text for display in a GtkTextView
+ * @Title: GtkTextBuffer
+ * @See_also: #GtkTextView, #GtkTextIter, #GtkTextMark
+ *
+ * You may wish to begin by reading the <link linkend="TextWidget">text widget
+ * conceptual overview</link> which gives an overview of all the objects and data
+ * types related to the text widget and how they work together.
+ */
+
+
 typedef struct _GtkTextLogAttrCache GtkTextLogAttrCache;
 
 struct _GtkTextBufferPrivate
diff --git a/gtk/gtktextbufferrichtext.h b/gtk/gtktextbufferrichtext.h
index 614b43dcfd..795247e561 100644
--- a/gtk/gtktextbufferrichtext.h
+++ b/gtk/gtktextbufferrichtext.h
@@ -30,12 +30,44 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GtkTextBufferSerializeFunc:
+ * @register_buffer: the #GtkTextBuffer for which the format is registered
+ * @content_buffer: the #GtkTextBuffer to serialize
+ * @start: start of the block of text to serialize
+ * @end: end of the block of text to serialize
+ * @length: Return location for the length of the serialized data
+ * @user_data: user data that was specified when registering the format
+ *
+ * A function that is called to serialize the content of a text buffer.
+ * It must return the serialized form of the content.
+ *
+ * Returns: a newly-allocated array of guint8 which contains the serialized
+ *   data, or %NULL if an error occurred
+ */
 typedef guint8 * (* GtkTextBufferSerializeFunc)   (GtkTextBuffer     *register_buffer,
                                                    GtkTextBuffer     *content_buffer,
                                                    const GtkTextIter *start,
                                                    const GtkTextIter *end,
                                                    gsize             *length,
                                                    gpointer           user_data);
+
+/**
+ * GtkTextBufferDeserializeFunc:
+ * @register_buffer: the #GtkTextBuffer the format is registered with
+ * @content_buffer: the #GtkTextBuffer to deserialize into
+ * @iter: insertion point for the deserialized text
+ * @data: data to deserialize
+ * @length: length of %data
+ * @create_tags: %TRUE if deserializing may create tags
+ * @user_data: user data that was specified when registering the format
+ * @error: return location for a #GError
+ *
+ * A function that is called to deserialize rich text that has been
+ * serialized with gtk_text_buffer_serialize(), and insert it at @iter.
+ *
+ * Returns: %TRUE on success, %FALSE otherwise
+ */
 typedef gboolean (* GtkTextBufferDeserializeFunc) (GtkTextBuffer     *register_buffer,
                                                    GtkTextBuffer     *content_buffer,
                                                    GtkTextIter       *iter,