Doc: Qt Concurrent: Link to essential usage information

Functions under the QtConcurrent namespace used to be documented
as header files, using the \headerfile command. These documents
have been since converted to standard pages using the \page
command, and the reference documentation for these functions
now live in the namespace page only.

However, the former pages contain useful usage information and
code snippets, but they've not been linked to from anywhere.

This change links to these pages from the module landing page,
as well as from the function reference doc.

Change-Id: Ia750d72d12503cec96ee2c9e202dd561e548cb24
Task-number: QTBUG-28977
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>

4 files changed, 66 insertions, 29 deletions

diff --git a/src/concurrent/doc/src/qtconcurrent-index.qdoc b/src/concurrent/doc/src/qtconcurrent-index.qdoc
index 2157280021..e57ebd2424 100644
--- a/src/concurrent/doc/src/qtconcurrent-index.qdoc
+++ b/src/concurrent/doc/src/qtconcurrent-index.qdoc
@@ -49,26 +49,35 @@
     applications:
 
     \list
+    \li \l {Concurrent Map and Map-Reduce}
+        \list
+            \li \l {QtConcurrent::map}{QtConcurrent::map()} applies a function
+                to every item in a container, modifying the items in-place.
+            \li \l {QtConcurrent::mapped}{QtConcurrent::mapped()} is like
+                map(), except that it returns a new container with the
+                modifications.
+            \li \l {QtConcurrent::mappedReduced}{QtConcurrent::mappedReduced()}
+                is like mapped(), except that the modified results are reduced
+                or folded into a single result.
+        \endlist
+
+    \li \l {Concurrent Filter and Filter-Reduce}
+    \list
+        \li \l {QtConcurrent::filter}{QtConcurrent::filter()} removes all items
+            from a container based on the result of a filter function.
+        \li \l {QtConcurrent::filtered}{QtConcurrent::filtered()} is like
+            filter(), except that it returns a new container with the filtered
+            results.
+        \li \l {QtConcurrent::filteredReduced}{QtConcurrent::filteredReduced()}
+            is like filtered(), except that the filtered results are reduced or
+            folded into a single result.
+    \endlist
 
-    \li \l {QtConcurrent::map}{QtConcurrent::map()} applies a function to every item in a container,
-    modifying the items in-place.
-
-    \li \l {QtConcurrent::mapped}{QtConcurrent::mapped()} is like map(), except that it returns a new
-    container with the modifications.
-
-    \li \l {QtConcurrent::mappedReduced}{QtConcurrent::mappedReduced()} is like mapped(), except that the
-    modified results are reduced or folded into a single result.
-
-    \li \l {QtConcurrent::filter}{QtConcurrent::filter()} removes all items from a container based on the
-    result of a filter function.
-
-    \li \l {QtConcurrent::filtered}{QtConcurrent::filtered()} is like filter(), except that it returns a new
-    container with the filtered results.
-
-    \li \l {QtConcurrent::filteredReduced}{QtConcurrent::filteredReduced()} is like filtered(), except that the
-    filtered results are reduced or folded into a single result.
-
-    \li \l {QtConcurrent::run}{QtConcurrent::run()} runs a function in another thread.
+    \li \l {Concurrent Run}
+    \list
+        \li \l {QtConcurrent::run}{QtConcurrent::run()} runs a function in
+            another thread.
+    \endlist
 
     \li QFuture represents the result of an asynchronous computation.
 
diff --git a/src/concurrent/qtconcurrentfilter.cpp b/src/concurrent/qtconcurrentfilter.cpp
index 2c539b5766..4b3f2368b8 100644
--- a/src/concurrent/qtconcurrentfilter.cpp
+++ b/src/concurrent/qtconcurrentfilter.cpp
@@ -179,6 +179,8 @@
     Calls \a filterFunction once for each item in \a sequence. If
     \a filterFunction returns \c true, the item is kept in \a sequence;
     otherwise, the item is removed from \a sequence.
+
+    \sa {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -188,6 +190,8 @@
     new Sequence of kept items. If \a filterFunction returns \c true, a copy of
     the item is put in the new Sequence. Otherwise, the item will \e not
     appear in the new Sequence.
+
+    \sa {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -197,6 +201,8 @@
     returns a new Sequence of kept items. If \a filterFunction returns \c true, a
     copy of the item is put in the new Sequence. Otherwise, the item will
     \e not appear in the new Sequence.
+
+    \sa {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -213,6 +219,8 @@
     QtConcurrent::UnorderedReduce. If \a reduceOptions is
     QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
     the original sequence.
+
+    \sa {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -229,6 +237,8 @@
     QtConcurrent::UnorderedReduce. If \a reduceOptions is
     QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
     of the original sequence.
+
+    \sa {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -239,6 +249,8 @@
   otherwise, the item is removed from \a sequence.
 
   \note This function will block until all items in the sequence have been processed.
+
+  \sa {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -251,7 +263,7 @@
 
   \note This function will block until all items in the sequence have been processed.
 
-  \sa filtered()
+  \sa filtered(), {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -265,7 +277,7 @@
   \note This function will block until the iterator reaches the end of the
   sequence being processed.
 
-  \sa filtered()
+  \sa filtered(), {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -285,7 +297,7 @@
 
   \note This function will block until all items in the sequence have been processed.
 
-  \sa filteredReduced()
+  \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
 */
 
 /*!
@@ -306,5 +318,5 @@
   \note This function will block until the iterator reaches the end of the
   sequence being processed.
 
-  \sa filteredReduced()
+  \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
 */
diff --git a/src/concurrent/qtconcurrentmap.cpp b/src/concurrent/qtconcurrentmap.cpp
index 43ade3a336..158bdb3887 100644
--- a/src/concurrent/qtconcurrentmap.cpp
+++ b/src/concurrent/qtconcurrentmap.cpp
@@ -229,6 +229,8 @@
     Calls \a function once for each item in \a sequence. The \a function is
     passed a reference to the item, so that any modifications done to the item
     will appear in \a sequence.
+
+    \sa {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -237,6 +239,8 @@
     Calls \a function once for each item from \a begin to \a end. The
     \a function is passed a reference to the item, so that any modifications
     done to the item will appear in the sequence which the iterators belong to.
+
+    \sa {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -245,6 +249,8 @@
     Calls \a function once for each item in \a sequence and returns a future
     with each mapped item as a result. You can use QFuture::const_iterator or
     QFutureIterator to iterate through the results.
+
+    \sa {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -253,6 +259,8 @@
     Calls \a function once for each item from \a begin to \a end and returns a
     future with each mapped item as a result. You can use
     QFuture::const_iterator or QFutureIterator to iterate through the results.
+
+    \sa {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -266,6 +274,8 @@
     Note that while \a mapFunction is called concurrently, only one thread at a
     time will call \a reduceFunction. The order in which \a reduceFunction is
     called is determined by \a reduceOptions.
+
+    \sa {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -281,6 +291,8 @@
     \a reduceFunction is called is undefined.
 
     \note QtConcurrent::OrderedReduce results in the ordered reduction.
+
+    \sa {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -292,7 +304,7 @@
 
   \note This function will block until all items in the sequence have been processed.
 
-  \sa map()
+  \sa map(), {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -305,7 +317,7 @@
   \note This function will block until the iterator reaches the end of the
   sequence being processed.
 
-  \sa map()
+  \sa map(), {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -316,7 +328,7 @@
 
   \note This function will block until all items in the sequence have been processed.
 
-  \sa mapped()
+  \sa mapped(), {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -333,7 +345,7 @@
   \note This function will block until the iterator reaches the end of the
   sequence being processed.
 
-  \sa mapped()
+  \sa mapped(), {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -348,7 +360,7 @@
 
   \note This function will block until all items in the sequence have been processed.
 
-  \sa mapped()
+  \sa mapped(), {Concurrent Map and Map-Reduce}
 */
 
 /*!
@@ -364,5 +376,5 @@
   \note This function will block until the iterator reaches the end of the
   sequence being processed.
 
-  \sa blockingMappedReduced()
+  \sa blockingMappedReduced(), {Concurrent Map and Map-Reduce}
 */
diff --git a/src/concurrent/qtconcurrentrun.cpp b/src/concurrent/qtconcurrentrun.cpp
index 42d085cc2a..fa791bd323 100644
--- a/src/concurrent/qtconcurrentrun.cpp
+++ b/src/concurrent/qtconcurrentrun.cpp
@@ -143,6 +143,8 @@
     canceling, pausing, or progress reporting. The QFuture returned can only
     be used to query for the running/finished status and the return value of
     the function.
+
+    \sa {Concurrent Run}
 */
 
 /*!
@@ -160,4 +162,6 @@
     canceling, pausing, or progress reporting. The QFuture returned can only
     be used to query for the running/finished status and the return value of
     the function.
+
+    \sa {Concurrent Run}
 */