text: convert comments to doxygen format

3 files changed, 127 insertions, 24 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 686e5d3..d7291b8 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -87,6 +87,7 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+default_role = "any"
 
 # -- Options for HTML output ----------------------------------------------
 
diff --git a/doc/index.rst b/doc/index.rst
index 1a0596c..be98c29 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,28 +1,7 @@
-.. Vis Editor documentation master file, created by
-   sphinx-quickstart on Fri Apr 28 21:45:05 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Vis Editor's documentation!
-======================================
+Vis Editor API Documenation
+===========================
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-C API Documentation Test
-========================
-
-.. doxygenstruct:: Text
-.. doxygenfunction:: text_insert
-
-Here we have an inline text.
-
-.. doxygenenum:: TextSaveMethod
-
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   text
diff --git a/doc/text.rst b/doc/text.rst
new file mode 100644
index 0000000..210336b
--- /dev/null
+++ b/doc/text.rst
@@ -0,0 +1,123 @@
+Text
+====
+
+The core text management data structure which supports efficient
+modifications and provides a byte string interface. Text positions
+are represented as ``size_t``.  Valid addresses are in range ``[0,
+text_size(txt)]``. An invalid position is denoted by `EPOS`. Access to
+the non-contigiuos pieces is available by means of an iterator interface
+or a copy mechanism. Text revisions are tracked in an history graph.
+
+.. note:: The text is assumed to be encoded in `UTF-8 <https://tools.ietf.org/html/rfc3629>`_.
+
+Load
+----
+
+.. doxygengroup:: load
+   :content-only:
+
+State
+-----
+
+.. doxygengroup:: state
+   :content-only:
+
+Modify
+------
+
+.. doxygengroup:: modify
+   :content-only:
+
+Access
+------
+
+The individual pieces of the text are not necessarily stored in a
+contiguous memory block. These functions perform a copy to such a region.
+
+.. doxygengroup:: access
+   :content-only:
+
+Iterator
+--------
+
+An iterator points to a given text position and provides interfaces to
+adjust said position or read the underlying byte value. Functions which
+take a ``char`` pointer will generally assign the byte value *after*
+the iterator was updated.
+
+.. doxygenstruct:: Iterator
+
+.. doxygengroup:: iterator
+   :content-only:
+
+Byte
+^^^^
+
+.. note:: For a read attempt at EOF (i.e. `text_size`) an artificial ``NUL``
+          byte which is not actually part of the file is returned.
+
+.. doxygengroup:: iterator_byte
+   :content-only:
+
+Codepoint
+^^^^^^^^^
+
+These functions advance to the next/previous leading byte of an UTF-8
+encoded Unicode codepoint by skipping over all continuation bytes of
+the form ``10xxxxxx``.
+
+.. doxygengroup:: iterator_code
+   :content-only:
+
+Grapheme Clusters
+^^^^^^^^^^^^^^^^^
+
+These functions advance to the next/previous grapheme cluster. 
+
+.. note:: The grapheme cluster boundaries are currently not implemented
+          according to `UAX#29 rules <http://unicode.org/reports/tr29>`_.
+          Instead a base character followed by arbitrarily many combining
+          character as reported by `wcwidth(3)` are skipped.
+
+.. doxygengroup:: iterator_char
+   :content-only:
+
+Lines
+-----
+
+Translate between 1 based line numbers and 0 based byte offsets.
+
+.. doxygengroup:: lines
+   :content-only:
+
+History
+-------
+
+Interfaces to the history graph.
+
+.. doxygengroup:: history
+   :content-only:
+
+Marks
+-----
+
+A mark keeps track of a text position. Subsequent text changes will update
+all marks placed after the modification point. Reverting to an older text
+state will hide all affected marks, redoing the changes will restore them.
+
+.. warning:: Due to an optimization cached modifications (i.e. no `text_snaphot`
+             was performed between setting the mark and issuing the changes) might
+             not adjust mark positions accurately.
+
+.. doxygentypedef:: Mark
+
+.. doxygendefine:: EMARK
+
+.. doxygengroup:: mark
+   :content-only:
+
+Save
+----
+
+.. doxygengroup:: save
+   :content-only: