From 9856f869f5cd4b7651c10b71b824aff4c006cf3b Mon Sep 17 00:00:00 2001
From: Ville Voutilainen <ville.voutilainen@qt.io>
Date: Tue, 5 Dec 2017 16:31:53 +0200
Subject: [PATCH] Fix documentation for function objects with map/reduce

The documentation claims that function objects just work with
map-reduce. They work for the map function, but not for the reduce
function. Making them work for the reduce function was deemed
too complex for questionable benefit, so this patch explains
the situation and provides a work-around.

Task-number: QTBUG-22710
Change-Id: I7f706468e36031bc261234310d331001b96e5137
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Nico Vertriest <nico.vertriest@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
---
 .../code/src_concurrent_qtconcurrentfilter.cpp     | 14 +++++++++++++-
 .../code/src_concurrent_qtconcurrentmap.cpp        | 12 ++++++++++++
 src/concurrent/qtconcurrentfilter.cpp              |  9 ++++++++-
 src/concurrent/qtconcurrentmap.cpp                 |  9 ++++++++-
 4 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp
index 9b15eeaa99..3cc1fe836c 100644
--- a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp
+++ b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp
@@ -169,5 +169,17 @@ struct StartsWith
 };
 
 QList<QString> strings = ...;
-QFuture<QString> fooString = QtConcurrent::filtered(images, StartsWith(QLatin1String("Foo")));
+QFuture<QString> fooString = QtConcurrent::filtered(strings, StartsWith(QLatin1String("Foo")));
 //! [13]
+
+//! [14]
+struct StringTransform
+{
+    void operator()(QString &result, const QString &value);
+};
+
+QFuture<QString> fooString =
+  QtConcurrent::filteredReduced<QString>(strings,
+                                         StartsWith(QLatin1String("Foo")),
+                                         StringTransform());
+//! [14]
diff --git a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp
index 183b82bb9a..9cf82c786a 100644
--- a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp
+++ b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp
@@ -157,6 +157,18 @@ QFuture<QSet<int> > totalColorDistribution = QtConcurrent::mappedReduced(images,
 QImage QImage::scaledToWidth(int width, Qt::TransformationMode) const;
 //! [10]
 
+//! [11]
+struct ImageTransform
+{
+    void operator()(QImage &result, const QImage &value);
+};
+
+QFuture<QImage> thumbNails =
+  QtConcurrent::mappedReduced<QImage>(images,
+                                      Scaled(100),
+                                      ImageTransform(),
+                                      QtConcurrent::SequentialReduce);
+//! [11]
 
 //! [13]
 QList<QImage> images = ...;
diff --git a/src/concurrent/qtconcurrentfilter.cpp b/src/concurrent/qtconcurrentfilter.cpp
index 3e3ed7cf68..d4e4656127 100644
--- a/src/concurrent/qtconcurrentfilter.cpp
+++ b/src/concurrent/qtconcurrentfilter.cpp
@@ -142,12 +142,19 @@
     \section2 Using Function Objects
 
     QtConcurrent::filter(), QtConcurrent::filtered(), and
-    QtConcurrent::filteredReduced() accept function objects, which can be used to
+    QtConcurrent::filteredReduced() accept function objects
+    for the filter function. These function objects can be used to
     add state to a function call. The result_type typedef must define the
     result type of the function call operator:
 
     \snippet code/src_concurrent_qtconcurrentfilter.cpp 13
 
+    For the reduce function, function objects are not directly
+    supported. Function objects can, however, be used
+    when the type of the reduction result is explicitly specified:
+
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 14
+
     \section2 Wrapping Functions that Take Multiple Arguments
 
     If you want to use a filter function takes more than one argument, you can
diff --git a/src/concurrent/qtconcurrentmap.cpp b/src/concurrent/qtconcurrentmap.cpp
index 884bf4b4f9..1ba5de355b 100644
--- a/src/concurrent/qtconcurrentmap.cpp
+++ b/src/concurrent/qtconcurrentmap.cpp
@@ -192,12 +192,19 @@
     \section2 Using Function Objects
 
     QtConcurrent::map(), QtConcurrent::mapped(), and
-    QtConcurrent::mappedReduced() accept function objects, which can be used to
+    QtConcurrent::mappedReduced() accept function objects
+    for the map function. These function objects can be used to
     add state to a function call. The result_type typedef must define the
     result type of the function call operator:
 
     \snippet code/src_concurrent_qtconcurrentmap.cpp 14
 
+    For the reduce function, function objects are not directly
+    supported. Function objects can, however, be used
+    when the type of the reduction result is explicitly specified:
+
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 11
+
     \section2 Wrapping Functions that Take Multiple Arguments
 
     If you want to use a map function that takes more than one argument you can