Augment documentation.

diff --git a/include/deal.II/base/task_result.h b/include/deal.II/base/task_result.h
index b9e62c9c13a6f53ef59c84dd43fea134c997c74a..77c588a3e2dcf4b6af9a82f9f45c387370dfb1ab 100644 (file)
--- a/include/deal.II/base/task_result.h
+++ b/include/deal.II/base/task_result.h
@@ -66,13 +66,22 @@ namespace Threads
    * hand, copying a TaskResult object after the computing task has finished
    * results in two copies of the returned object.
    *
-   * This class can also be compared with `std::future<T>`. That class also
-   * represents the result of a pending operation, but it lacks the specifics
-   * of what kind of operation that is. As a consequence, it can *wait* for
+   * This class can also be compared with
+   * [`std::future`](https://en.cppreference.com/w/cpp/thread/future). That
+   * class also represents the result of a pending operation, but it lacks the
+   * specifics of what kind of operation that is (in particular, it does not
+   * know whether a task, a thread, or a `std::packaged_task` will eventually
+   * produce the value). As a consequence, it can *wait* for
    * the result to become available, but it lacks the knowledge to detect
    * certain common programming mistakes such as those described in the
    * documentation of the destructor of this class, or of this class's
-   * `operator=()`.
+   * `operator=()`. Another significant difference is that
+   * one can only call `std::future::get()` once, whereas one
+   * can call Threads::Task::return_value() as many times as desired. It is,
+   * thus, comparable to the
+   * [`std::shared_future`](https://en.cppreference.com/w/cpp/thread/shared_future)
+   * class. However, `std::shared_future` can not be used for types that can not
+   * be copied -- a particular restriction for `std::unique_ptr`, for example.
    */
   template <typename T>
   class TaskResult

diff --git a/include/deal.II/base/thread_management.h b/include/deal.II/base/thread_management.h
index db0a9b7a60e8c7d08ef3d8889ef967ac20d4bce3..b69d4611a3e4151f1ef45c666323e8c3735b4340 100644 (file)
--- a/include/deal.II/base/thread_management.h
+++ b/include/deal.II/base/thread_management.h
@@ -465,21 +465,22 @@ namespace Threads
    * run things in the background when there is no immediate need for the
    * result, or if there are other things that could well be done in parallel.
    * Whenever the result of that background task is needed, one can call either
-   * join() to just wait for the task to finish, or return_value() to obtain the
-   * value that was returned by the function that was run on that background
-   * task.
+   * Threads::Task::join() to just wait for the task to finish, or
+   * Threads::Task::return_value() to obtain the value that was returned by the
+   * function that was run on that background task. In both of these cases, one
+   * continues to reference the *operation* (namely, the Task object) that was
+   * in charge of computing the returned value. An alternative is to use the
+   * Threads::TaskResult class that references the *object* being computed
+   * rather than the task that computes it.
    *
-   * This class is conceptually similar to the
+   * This class is related to, but semantically not the same as, the
    * [`std::future`](https://en.cppreference.com/w/cpp/thread/future) class that
    * is returned by
    * [`std::async`](https://en.cppreference.com/w/cpp/thread/async) (which is
    * itself similar to what Threads::new_task() does). The principal conceptual
-   * difference is that one can only call `std::future::get()` once, whereas one
-   * can call Threads::Task::return_value() as many times as desired. It is,
-   * thus, comparable to the
-   * [`std::shared_future`](https://en.cppreference.com/w/cpp/thread/shared_future)
-   * class. However, `std::shared_future` can not be used for types that can not
-   * be copied -- a particular restriction for `std::unique_ptr`, for example.
+   * difference is that `std::future` references the *returned object* (like
+   * Threads::TaskResult) whereas the current object references the task that
+   * computes that result.
    *
    * @ingroup threads
    */