view: clean up and add documentation

doc/index.rst

@@ -6,6 +6,7 @@ Vis Editor API Documenation
 
    vis
    text
+   view
    buffer
    array
    map

doc/view.rst

@@ -0,0 +1,110 @@
+View
+====
+
+Provides a viewport of a text instance and mangages selections.
+
+Lifecycle
+---------
+
+.. doxygengroup:: view_life
+   :content-only:
+
+Viewport
+--------
+
+The cursor of the primary selection is always visible.
+
+.. doxygengroup:: view_viewport
+   :content-only:
+
+Dimension
+---------
+
+.. doxygengroup:: view_size
+   :content-only:
+
+Draw
+----
+
+.. doxygengroup:: view_draw
+   :content-only:
+
+Selections
+----------
+
+A selection is a non-empty, directed range with two endpoints called *cursor*
+and *anchor*. A selection can be anchored in which case the anchor remains
+fixed while only the position of the cursor is adjusted. For non-anchored
+selections both endpoints are updated. A singleton selection
+covers one character on which both cursor and anchor reside. There always
+exists a primary selection which remains visible (i.e. changes to its position
+will adjust the viewport).
+
+Creation and Destruction
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. doxygengroup:: view_selnew
+   :content-only:
+
+Navigation
+~~~~~~~~~~
+
+.. doxygengroup:: view_navigate
+   :content-only:
+
+Cover
+~~~~~
+
+.. doxygengroup:: view_cover
+   :content-only:
+
+Anchor
+~~~~~~
+
+.. doxygengroup:: view_anchor
+   :content-only:
+
+Cursor
+~~~~~~
+
+Selection endpoint to which cursor motions apply.
+
+Properties
+^^^^^^^^^^
+
+.. doxygengroup:: view_props
+   :content-only:
+
+Placement
+^^^^^^^^^
+
+.. doxygengroup:: view_place
+   :content-only:
+
+Motions
+^^^^^^^^
+
+These functions perform motions based on the current selection cursor position.
+
+.. doxygengroup:: view_motions
+   :content-only:
+
+Primary Selection
+~~~~~~~~~~~~~~~~~
+
+These are convenience function which operate on the primary selection.
+
+.. doxygengroup:: view_primary
+   :content-only:
+
+Save and Restore
+~~~~~~~~~~~~~~~~
+
+.. doxygengroup:: view_save
+   :content-only:
+
+Style
+-----
+
+.. doxygengroup:: view_style
+   :content-only:

view.c

@@ -105,6 +105,14 @@ static const SyntaxSymbol symbols_default[] = {
 
 static Cell cell_unused;
 
+
+/* move visible viewport n-lines up/down, redraws the view but does not change
+ * cursor position which becomes invalid and should be corrected by calling
+ * view_cursor_to. the return value indicates wether the visible area changed.
+ */
+static bool view_viewport_up(View *view, int n);
+static bool view_viewport_down(View *view, int n);
+
 static void view_clear(View *view);
 static bool view_addch(View *view, Cell *cell);
 static void view_cursors_free(Cursor *c);
@@ -549,7 +557,7 @@ static size_t cursor_set(Cursor *cursor, Line *line, int col) {
 	return pos;
 }
 
-bool view_viewport_down(View *view, int n) {
+static bool view_viewport_down(View *view, int n) {
 	Line *line;
 	if (view->end >= text_size(view->text))
 		return false;
@@ -563,7 +571,7 @@ bool view_viewport_down(View *view, int n) {
 	return true;
 }
 
-bool view_viewport_up(View *view, int n) {
+static bool view_viewport_up(View *view, int n) {
 	/* scrolling up is somewhat tricky because we do not yet know where
 	 * the lines start, therefore scan backwards but stop at a reasonable
 	 * maximum in case we are dealing with a file without any newlines