GSequence: move docs from tmpl to .c

diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore
index fd5ae42..22adad0 100644 (file)
--- a/docs/reference/glib/tmpl/.gitignore
+++ b/docs/reference/glib/tmpl/.gitignore
@@ -5,6 +5,7 @@ gvarianttype.sgml
 hash_tables.sgml
 option.sgml
 random_numbers.sgml
+sequence.sgml
 shell.sgml
 threads.sgml
 timers.sgml

diff --git a/docs/reference/glib/tmpl/sequence.sgml b/docs/reference/glib/tmpl/sequence.sgml
deleted file mode 100644 (file)
index 3f50076..0000000
--- a/docs/reference/glib/tmpl/sequence.sgml
+++ /dev/null
@@ -1,432 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-Sequences
-
-<!-- ##### SECTION Short_Description ##### -->
-scalable lists
-
-<!-- ##### SECTION Long_Description ##### -->
-
-<para>
-The #GSequence data structure has the API of a list, but is
-implemented internally with a balanced binary tree. This means that it
-is possible to maintain a sorted list of n elements in time O(n log
-n). The data contained in each element can be either integer values, by
-using of the 
-<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
-or simply pointers to any type of data.
-</para>
-
-<para>
-A #GSequence is accessed through <firstterm>iterators</firstterm>,
-represented by a #GSequenceIter. An iterator represents a position
-between two elements of the sequence. For example, the
-<firstterm>begin</firstterm> iterator represents the gap immediately
-before the first element of the sequence, and the
-<firstterm>end</firstterm> iterator represents the gap immediately
-after the last element. In an empty sequence, the begin and end
-iterators are the same.
-</para>
-
-<para>
-Some methods on #GSequence operate on ranges of items. For example
-g_sequence_foreach_range() will call a user-specified function on each
-element with the given range. The range is delimited by the gaps
-represented by the passed-in iterators, so if you pass in the begin
-and end iterators, the range in question is the entire sequence.
-</para>
-
-
-<para>
-The function g_sequence_get() is used with an iterator to access the
-element immediately following the gap that the iterator
-represents. The iterator is said to <firstterm>point</firstterm> to
-that element.
-</para>
-
-<para>
-Iterators are stable across most operations on a #GSequence. For
-example an iterator pointing to some element of a sequence will
-continue to point to that element even after the sequence is
-sorted. Even moving an element to another sequence using for example
-g_sequence_move_range() will not invalidate the iterators pointing to
-it. The only operation that will invalidate an iterator is when the
-element it points to is removed from any sequence.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GSequence ##### -->
-<para>
-The <structname>GSequence</structname> struct is an opaque data type
-representing a <link linkend="glib-Sequences">Sequence</link> data type.
-</para>
-
-
-<!-- ##### TYPEDEF GSequenceIter ##### -->
-<para>
-The <structname>GSequenceIter</structname> struct is an opaque data
-type representing an iterator pointing into a #GSequence.
-</para>
-
-
-<!-- ##### USER_FUNCTION GSequenceIterCompareFunc ##### -->
-<para>
-A #GSequenceIterCompareFunc is a function used to compare
-iterators. It must return zero if the iterators compare equal, a
-negative value if @a comes before @b, and a positive value if @b comes
-before @a.
-</para>
-
-@a: a #GSequenceIter
-@b: a #GSequenceIter
-@data: user data
-@Returns: zero if the iterators are equal, a negative value if @a
-comes before @b, and a positive value if @b comes before @a.
-
-
-<!-- ##### FUNCTION g_sequence_new ##### -->
-<para>
-
-</para>
-
-@data_destroy: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_free ##### -->
-<para>
-
-</para>
-
-@seq: 
-
-
-<!-- ##### FUNCTION g_sequence_get_length ##### -->
-<para>
-
-</para>
-
-@seq: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_foreach ##### -->
-<para>
-
-</para>
-
-@seq: 
-@func: 
-@user_data: 
-
-
-<!-- ##### FUNCTION g_sequence_foreach_range ##### -->
-<para>
-
-</para>
-
-@begin: 
-@end: 
-@func: 
-@user_data: 
-
-
-<!-- ##### FUNCTION g_sequence_sort ##### -->
-<para>
-
-</para>
-
-@seq: 
-@cmp_func: 
-@cmp_data: 
-
-
-<!-- ##### FUNCTION g_sequence_sort_iter ##### -->
-<para>
-
-</para>
-
-@seq: 
-@cmp_func: 
-@cmp_data: 
-
-
-<!-- ##### FUNCTION g_sequence_get_begin_iter ##### -->
-<para>
-
-</para>
-
-@seq: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_get_end_iter ##### -->
-<para>
-
-</para>
-
-@seq: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_get_iter_at_pos ##### -->
-<para>
-
-</para>
-
-@seq: 
-@pos: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_append ##### -->
-<para>
-
-</para>
-
-@seq: 
-@data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_prepend ##### -->
-<para>
-
-</para>
-
-@seq: 
-@data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_insert_before ##### -->
-<para>
-
-</para>
-
-@iter: 
-@data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_move ##### -->
-<para>
-
-</para>
-
-@src: 
-@dest: 
-
-
-<!-- ##### FUNCTION g_sequence_swap ##### -->
-<para>
-
-</para>
-
-@a: 
-@b: 
-
-
-<!-- ##### FUNCTION g_sequence_insert_sorted ##### -->
-<para>
-
-</para>
-
-@seq: 
-@data: 
-@cmp_func: 
-@cmp_data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_insert_sorted_iter ##### -->
-<para>
-
-</para>
-
-@seq: 
-@data: 
-@iter_cmp: 
-@cmp_data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_sort_changed ##### -->
-<para>
-
-</para>
-
-@iter: 
-@cmp_func: 
-@cmp_data: 
-
-
-<!-- ##### FUNCTION g_sequence_sort_changed_iter ##### -->
-<para>
-
-</para>
-
-@iter: 
-@iter_cmp: 
-@cmp_data: 
-
-
-<!-- ##### FUNCTION g_sequence_remove ##### -->
-<para>
-
-</para>
-
-@iter: 
-
-
-<!-- ##### FUNCTION g_sequence_remove_range ##### -->
-<para>
-
-</para>
-
-@begin: 
-@end: 
-
-
-<!-- ##### FUNCTION g_sequence_move_range ##### -->
-<para>
-
-</para>
-
-@dest: 
-@begin: 
-@end: 
-
-
-<!-- ##### FUNCTION g_sequence_search ##### -->
-<para>
-
-</para>
-
-@seq: 
-@data: 
-@cmp_func: 
-@cmp_data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_search_iter ##### -->
-<para>
-
-</para>
-
-@seq: 
-@data: 
-@iter_cmp: 
-@cmp_data: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_get ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_set ##### -->
-<para>
-
-</para>
-
-@iter: 
-@data: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_is_begin ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_is_end ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_next ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_prev ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_get_position ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_move ##### -->
-<para>
-
-</para>
-
-@iter: 
-@delta: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_get_sequence ##### -->
-<para>
-
-</para>
-
-@iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_iter_compare ##### -->
-<para>
-
-</para>
-
-@a: 
-@b: 
-@Returns: 
-
-
-<!-- ##### FUNCTION g_sequence_range_get_midpoint ##### -->
-<para>
-
-</para>
-
-@begin: 
-@end: 
-@Returns: 
-
-

diff --git a/glib/gsequence.c b/glib/gsequence.c
index b17e6ec..ee00708 100644 (file)
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -23,8 +23,77 @@
 #include "glib.h"
 #include "galias.h"
 
+/**
+ * SECTION: sequence
+ * @title: Sequences
+ * @short_description: scalable lists
+ *
+ * The #GSequence data structure has the API of a list, but is
+ * implemented internally with a balanced binary tree. This means that
+ * it is possible to maintain a sorted list of n elements in time O(n
+ * log n). The data contained in each element can be either integer
+ * values, by using of the <link
+ * linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
+ * or simply pointers to any type of data.
+ *
+ * A #GSequence is accessed through <firstterm>iterators</firstterm>,
+ * represented by a #GSequenceIter. An iterator represents a position
+ * between two elements of the sequence. For example, the
+ * <firstterm>begin</firstterm> iterator represents the gap immediately
+ * before the first element of the sequence, and the
+ * <firstterm>end</firstterm> iterator represents the gap immediately
+ * after the last element. In an empty sequence, the begin and end
+ * iterators are the same.
+ *
+ * Some methods on #GSequence operate on ranges of items. For example
+ * g_sequence_foreach_range() will call a user-specified function on
+ * each element with the given range. The range is delimited by the
+ * gaps represented by the passed-in iterators, so if you pass in the
+ * begin and end iterators, the range in question is the entire
+ * sequence.
+ *
+ * The function g_sequence_get() is used with an iterator to access the
+ * element immediately following the gap that the iterator represents.
+ * The iterator is said to <firstterm>point</firstterm> to that element.
+ *
+ * Iterators are stable across most operations on a #GSequence. For
+ * example an iterator pointing to some element of a sequence will
+ * continue to point to that element even after the sequence is sorted.
+ * Even moving an element to another sequence using for example
+ * g_sequence_move_range() will not invalidate the iterators pointing
+ * to it. The only operation that will invalidate an iterator is when
+ * the element it points to is removed from any sequence.
+ **/
+
+/**
+ * GSequenceIter:
+ *
+ * The #GSequenceIter struct is an opaque data type representing an
+ * iterator pointing into a #GSequence.
+ **/
+
+/**
+ * GSequenceIterCompareFunc:
+ * @a: a #GSequenceIter
+ * @b: a #GSequenceIter
+ * @data: user data
+ * @Returns: zero if the iterators are equal, a negative value if @a
+ *           comes before @b, and a positive value if @b comes before
+ *           @a.
+ *
+ * A #GSequenceIterCompareFunc is a function used to compare iterators.
+ * It must return zero if the iterators compare equal, a negative value
+ * if @a comes before @b, and a positive value if @b comes before @a.
+ **/
+
 typedef struct _GSequenceNode GSequenceNode;
 
+/**
+ * GSequence:
+ *
+ * The #GSequence struct is an opaque data type representing a
+ * <link linkend="glib-Sequences">Sequence</link> data type.
+ **/
 struct _GSequence
 {
   GSequenceNode *       end_node;