[evolution-data-server/openismus-work-3-8] EDataBookCursor docs fixup

[Tristan Van Berkom <tvb src gnome org>]

commit 7c4d4b5a3fd7acb7fb55a895e4ede381a02fd71c
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Tue Oct 22 22:55:49 2013 +0200

    EDataBookCursor docs fixup

 addressbook/libedata-book/e-data-book-cursor.c |    5 ++++-
 addressbook/libedata-book/e-data-book-cursor.h |   10 +++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)
---
diff --git a/addressbook/libedata-book/e-data-book-cursor.c b/addressbook/libedata-book/e-data-book-cursor.c
index 43092ce..a5e7cff 100644
--- a/addressbook/libedata-book/e-data-book-cursor.c
+++ b/addressbook/libedata-book/e-data-book-cursor.c
@@ -813,7 +813,10 @@ e_data_book_cursor_set_sexp (EDataBookCursor     *cursor,
  * %E_CLIENT_ERROR_OUT_OF_SYNC error if the @revision_guard does not match
  * the current addressbook revision.
  *
- * Returns: The number of contacts traversed if successfull, otherwise -1 is
+ * An explanation of how stepping is expected to behave can be found
+ * in the <link linkend="cursor-iteration">user facing reference documentation</link>.
+ *
+ * Returns: The number of contacts traversed if successful, otherwise -1 is
  * returned and @error is set.
  *
  * Since: 3.12
diff --git a/addressbook/libedata-book/e-data-book-cursor.h b/addressbook/libedata-book/e-data-book-cursor.h
index eb7a879..8d938b5 100644
--- a/addressbook/libedata-book/e-data-book-cursor.h
+++ b/addressbook/libedata-book/e-data-book-cursor.h
@@ -126,8 +126,8 @@ typedef gint (*EDataBookCursorStepFunc) (EDataBookCursor     *cursor,
  *
  * Method type for #EDataBookCursorClass.set_alphabetic_index()
  *
- * Sets the current cursor position to point to an index into the
- * active alphabet.
+ * Sets the cursor state to point to an 
+ * <link linkend="cursor-alphabet">index into the active alphabet</link>.
  *
  * The implementing class must check that @locale matches the current
  * locale setting of the underlying database and report an %E_CLIENT_ERROR_OUT_OF_SYNC
@@ -161,10 +161,14 @@ typedef gboolean (*EDataBookCursorSetAlphabetIndexFunc) (EDataBookCursor     *cu
  * contact). A position of %0 indicates that the cursor is situated in
  * a position that is before and after the entire result set. The cursor
  * position should be %0 at creation time, and should start again from
- * the symbolic %0 position whenever %E_BOOK_CURSOR_ORIGIN_RESET is
+ * the symbolic %0 position whenever %E_BOOK_CURSOR_ORIGIN_BEGIN is
  * specified in the #EDataBookCursorClass.step() method (or whenever
  * moving the cursor beyond the end of the result set).
  *
+ * If the cursor is positioned beyond the end of the list, then
+ * the position should be the total amount of contacts available
+ * in the list (as returned through the @total argument) plus one.
+ *
  * This method is called by e_data_book_cursor_recalculate() and in some
  * other cases where @cursor's current position and total must be
  * recalculated from scratch.