qdoc: Correct some links in QtEnginio

Several links in the Enginio docs are either broken, or they got to
the wrong page. The docs also need revising.

Change-Id: I90edd39a94b6922d5fe4423f684fb8004de0dee3
Task-number: QTBUG-40919
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

3 files changed, 110 insertions, 60 deletions

diff --git a/examples/enginio/quick/image-gallery/doc/src/image-gallery.qdoc b/examples/enginio/quick/image-gallery/doc/src/image-gallery.qdoc
index 923b300..617214a 100644
--- a/examples/enginio/quick/image-gallery/doc/src/image-gallery.qdoc
+++ b/examples/enginio/quick/image-gallery/doc/src/image-gallery.qdoc
@@ -64,17 +64,17 @@
 
     \section1 The example code
 
-    The first step is to set up the \l Enginio::EnginioClient client.
+    The first step is to set up the \l {EnginioClient} {Enginio client}.
     \snippet image-gallery/image-gallery.qml client
 
-    The model gets initialized with the client declared above.
+    Then the model is initialized with that client.
     \snippet image-gallery/image-gallery.qml model
 
     A delegate is needed to present the images nicely.
     The model is used to get the list of image objects, but the images
     are only attached to the objects as file references.
     Thus the image's thumbnail is fetched by each delegate.
-    \note in a real application it might be necessary to cache the images.
+    \note In a real application it might be necessary to cache the images.
 
     The \c Component.onCompleted function is used to fetch the image.
     When the delegate is created, it has the JSON image object data.
diff --git a/examples/enginio/quick/todos/doc/src/todos.qdoc b/examples/enginio/quick/todos/doc/src/todos.qdoc
index 7a150be..d31e804 100644
--- a/examples/enginio/quick/todos/doc/src/todos.qdoc
+++ b/examples/enginio/quick/todos/doc/src/todos.qdoc
@@ -31,17 +31,21 @@
     \ingroup enginio-qml-examples
     \inmodule enginio-qml
 
-    In this example a simple list of objects is displayed in a ListView.
-    Each item in the list is a "To Do" object which can be \e done or \e{not yet done}.
-    Todos can be added and removed (when hovering with the mouse).
+    In this example a simple list of objects is displayed in a
+    ListView.  Each item in the list is a "To Do" object which can be
+    \e done or \e{not yet done}.  Todos can be added and removed (when
+    hovering with the mouse).
+
     \image todolist.png
 
-    In this simple schema the objects will only have two properties that are added
-    to the default properties (such as creation date, which always exists):
-    a string \c title and a bool \c completed. The object type will be created
-    when a call to create, or, in this case, a call to \l{Enginio::EnginioModel::append()}{EnginioModel::append()} is made.
+    In this simple schema, the objects will only have two properties
+    that are added to the default properties (such as creation date,
+    which always exists): a string \c title and a bool \c completed.
+    The object type will be created when a call to create, or, in this
+    case, a call to \l{EnginioModel::append()}{EnginioModel::append()}
+    is made.
 
-    A todo object will look like this (in JSON):
+    A todo object will look like this in \l {http://json.org} {JSON}:
     \code
 {
   "title": "Buy Milk",
@@ -52,11 +56,12 @@
     The example uses Qt Quick Controls, Layouts, and Enginio.
     \snippet todos/todo.qml imports
 
-    The first step is to create an \l{Enginio::EnginioModel} and
-    the Enginio instance with the backend configuration.
-    To get nice debug output in case something goes wrong, the onError signal in
-    Enginio is handled. Since the error is a JSON object, JSON.stringify is used
-    to format it to a string.
+    The first step is to create an \l{Enginio::EnginioModel} {Enginio model} and
+    its \l {EnginioClient} {Enginio client} with the backend configuration.
+    To get nice debug output in case something goes wrong, the client's
+    \l {EnginioClient::error} {onError} signal handler is implented. Since the
+    error is a \l {http://www.ecma-international.org/ecma-262/5.1/#sec-15.12}
+    {JSON object}, JSON.stringify is used to format it to a string.
 
     \snippet todos/todo.qml model
 
@@ -64,15 +69,19 @@
     properties of the Enginio objects are used.
     \snippet todos/todo.qml view
 
-    It is easy to add a new object to the model.  By using the \l onAccepted
-    signal handler of a \l TextField, the data is appended to the model. After appending
-    the new Todo, the text gets cleared so that a new Todo can be entered.
+    It is easy to add a new Todo object to the model using a \l {TextInput}.
+    By implementing the \l {TextInput::accepted} {onAccepted} signal handler,
+    the Todo data is appended to the model. After appending the new Todo, the
+    \l {TextInput::text} {text property} is cleared so that the next Todo can
+    be entered.
 
     \snippet todos/todo.qml append
 
-    Inside the delegate, the data for the index is available by using the property names (\e title and \e completed).
-    The \e title property is directly assigned to the text displayed on each list item. The \e completed
-    boolean is used to display the item with a strikeout font and a light color.
+    Inside the delegate, the data for the index is available by using
+    the property names (\e title and \e completed).  The \e title
+    property is directly assigned to the text displayed on each list
+    item. The \e completed boolean is used to display the item with a
+    strikeout font and a light color.
 
     \snippet todos/todo.qml delegate-properties
 
diff --git a/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc b/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc
index 69445d4..114e614 100644
--- a/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc
+++ b/examples/enginio/widgets/todos-cpp/doc/src/todos-cpp.qdoc
@@ -27,21 +27,25 @@
 /*!
     \title Enginio C++ Examples - Todos
     \example todos-cpp
-    \brief The Todo example shows how to use the \l {EnginioModelCpp}{EnginioModel} with Qt Widgets.
+    \brief The Todo example shows how to use the \l {EnginioModel} with Qt Widgets.
     \ingroup enginio-examples
     \inmodule enginio-qt
 
-    In this example, a simple list of objects is displayed in a \l QListView.
-    Each item in the list is a "To Do" object which can be "done" or "not yet done".
-    Todos can be added, removed, or altered.
+    In this example, a list of objects is displayed in a \l QTreeView.
+    Each item in the list is a \c {Todo} object, which can be marked
+    \c {Done} or \c {Not done}.  A \c {Todo} can be added, removed,
+    or altered. We will be using the classes and concepts duscussed in
+    \l {Model/View Programming} {Model/View Programming}.
+
     \image todo-example.png
 
-    In this simple schema the objects will have two properties that are added
-    to the default properties (such as creation date which always exists):
-    a string "title" and a bool "completed". The object type will be created
-    when a call to create, or in this case EnginoModel::append(), is made.
+    In this simple schema, each \c {ToDo} object will have two properties:
+    a \c {string} named \c {title} and a \c {bool} named \c {completed}.
+    These properties are added to the default properties e.g.: creation date,
+    which always exist.
+
+    A \c {Todo} object will look like this in \l {http://json.org} {JSON}:
 
-    A todo object will look like this (in JSON):
     \code
 {
   "title": "Buy Milk",
@@ -49,34 +53,67 @@
 }
     \endcode
 
-    The first step is to create a TodosModel which inherits \l [CPP] {EnginioModel},
-    and defines the main roles which will be used. As we are interested in the To Do \c title
-    and the \c completed information we need to define these two roles.
-    \snippet todos-cpp/todosmodel.h definition
-
-    By default, views (for example \l QListView) use the \l{Qt::ItemDataRole} role to display or edit the content.
-    The newly created \l [CPP] {EnginioModel} is empty and defines basic roles. Most roles are created
-    dynamically, based on the JSON datastructure.  They have no predefined value in the \l Qt::ItemDataRole enum.
-    \l [CPP] {EnginioModel} automatically populates itself as soon as the
-    \l{EnginioModel::query}{query} and \l{EnginioModel::client}{client} properties have been set.
-    When the data is downloaded, the model resets itself, and sets up the internal data cache and roles names.
-    \l [CPP] {EnginioModel} guesses the role names based on heuristics. It may be wrong if not all
-    objects received from the backend have exactly the same structure. For example, a property can be missing
-    in certain objects. To protect against such cases, we overload \l{EnginioModel::roleNames()}{roleNames()}.
-    Overriding \l{EnginioModel::roleNames()}{roleNames()} can also be used to match default Qt roles to the named
-    ones.
+    A ToDo object can be created and appended to an EnginioModel using
+    \l {EnginioModel::append()} {append()}, as shown in
+    \l {mainwindow_appenditem} {MainWindow::appendItem()}. Alternatively,
+    if many ToDo objects are to be added to the model all at once, they
+    can be inserted directly into the server database via the model's
+    \l {EnginioClient} {Enginio client}. The client is obtained from
+    the model with \l {EnginioModel::client()} {client()}. Then the
+    ToDo objects are inserted into the server database with the client's
+    \l {EnginioClient::create()} {create()} function. The model can then
+     be reloaded from the server with \l {EnginioModel::reload()} {reload()}.
+
+    But first we must create some infrastructure. Our \c{TodosModel}
+    class is declared in \l{todos-cpp/todosmodel.h}. It inherits
+    \l[CPP]{EnginioModel}, which is a \l{QAbstractListModel}{list
+    model}. We add two roles to the \l {Enginio::Role} {Enginio::Role
+    enum}, chosen for the new properties, one for the ToDo \c title
+    and one for marking a ToDo as \c{completed}. We assign enum values
+    to the new roles, equating \c{TitleRole} to
+    \l{Enginio::CustomPropertyRole}, which is itself equated to
+    \l{Qt::UserRole} + 10.  \snippet todos-cpp/todosmodel.h definition
+
+    The new roles can be used for displaying and editing the values of
+    the new properties. Views of the model also use roles from in
+    \l{Qt::ItemDataRole} enum. The example's view is a \l {QTreeView},
+    as shown in the \l{todos-cpp/mainwindow.h} {MainWindow class},
+    which holds a pointer to the view, a pointer to the
+    \l{EnginioClient} {client}, and a pointer to the
+    \l{todos-cpp/todosmodel.h} {model}.
+
+    A new \l [CPP] {EnginioModel} is empty. It automatically populates itself
+    from the server, when its \l{EnginioModel::query}{query} and
+    \l{EnginioModel::client}{client} properties have both been set. In the
+    example, these properties are set in the constructor for the
+    \l {todos-cpp/mainwindow.cpp} {main window}. The \l {EnginioClient} is
+    created first. Then an instance of the \c ToDosModel is created, and its
+    client is set using EnginioModel::setClient(). Then the query is created
+    as a QJsonObject, and the model's query is set using EnginioModel::setQuery().
+
+    Once the ToDo data has been downloaded, the model resets itself, and sets up
+    the internal data cache and roles names. \l [CPP] {EnginioModel} guesses the
+    role names based on heuristics. It may be wrong if not all objects received
+    from the backend have exactly the same structure. For example, a property can
+    be missing in certain objects. To protect against such cases, we overload
+    \l{EnginioModel::roleNames()}{roleNames()}.  Overriding
+    \l{EnginioModel::roleNames()}{roleNames()} can also be used to
+    match default Qt roles to the named ones.
 
     \snippet todos-cpp/todosmodel.cpp roleNames
 
-    In this example we map the \l Qt::DisplayRole and \l Qt::EditRole to the \c title property in the JSON.
-    This way the right string is shown by default and editing works as expected.
+    In this example, we map the \l Qt::DisplayRole and \l Qt::EditRole
+    to the \c title property in the JSON.  This way the right string
+    is shown by default and editing works as expected.
 
-    Remember to always call the base class implementation to avoid situations in which the internal cache is not in sync.
+    Remember to always call the base class implementation to avoid
+    situations in which the internal cache is not in sync.
 
-    By default \l [CPP] {EnginioModel} operates on \l{QJsonValue}, and that is
-    what the \l{EnginioModel::data()}{data()} function returns inside the \l QVariant, but standard
-    views, such as \l QListView, use predefined roles which do not map directly to our roles.
-    That is why we need to write a mapping between them:
+    By default \l [CPP] {EnginioModel} operates on \l{QJsonValue}, and
+    that is what the \l{EnginioModel::data()}{data()} function returns
+    inside the \l QVariant, but standard views, such as \l QListView,
+    use predefined roles which do not map directly to our roles.  That
+    is why we need to write a mapping between them:
 
     \snippet todos-cpp/todosmodel.cpp data
 
@@ -84,19 +121,23 @@
 
     \snippet todos-cpp/mainwindow.cpp client
 
-    It is used by the model to connect to the Enginio backend. Next we need to construct
-    and configure our model too. The configuration is based on two steps, assigning
-    an \l {EnginioClient} instance and by creating a query.
+    It is used by the model to connect to the Enginio backend. Next we
+    need to construct and configure our model too. The configuration
+    is based on two steps, assigning an \l {EnginioClient} instance
+    and by creating a query.
 
     \snippet todos-cpp/mainwindow.cpp model
 
-    The model has to be assigned to a view. In our case it is a \l QListView.
+    The model has to be assigned to a view. In this example it is a
+    \l QTreeView.
 
     \snippet todos-cpp/mainwindow.cpp assignModel
 
-    To make the application fully functional, a way to add and remove "To Dos" is needed.
-    To do so, we need to connect the correct buttons to slots for adding a new item:
+    To make the application fully functional, a way to add and remove
+    a Todo is needed.  To do so, we need to connect the correct
+    buttons to slots for adding a new item:
 
+    \target mainwindow_appenditem
     \snippet todos-cpp/mainwindow.cpp appendItem
 
     and for removing it: