doc/doxygen: backport documentation updates from texinfo

doc/doxygen/chapters/advanced_examples.doxy

@@ -824,8 +824,9 @@ To benefit from parallel tasks, a parallel-task-aware StarPU scheduler has to
 be used. When exposed to codelets with a Fork or SPMD flag, the <c>pheft</c>
 (parallel-heft) and <c>peager</c> (parallel eager) schedulers will indeed also
 try to execute tasks with several CPUs. It will automatically try the various
-available combined worker sizes and thus be able to avoid choosing a large
-combined worker if the codelet does not actually scale so much.
+available combined worker sizes (making several measurements for each
+worker size) and thus be able to avoid choosing a large combined
+worker if the codelet does not actually scale so much.
 
 \subsection Combined_workers Combined workers
 

doc/doxygen/chapters/api/data_management.doxy

@@ -55,7 +55,11 @@ value of the provided buffer is simply ignored for now.
 todo
 \var starpu_data_access_mode::STARPU_COMMUTE
 \ingroup API_Data_Management
-todo
+In addition to that, ::STARPU_COMMUTE can be passed along ::STARPU_W
+or ::STARPU_RW to express that StarPU can let tasks commute, which is
+useful e.g. when bringing a contribution into some data, which can be
+done in any order (but still require sequential consistency against
+reads or non-commutative writes).
 
 @name Basic Data Management API
 \ingroup API_Data_Management

doc/doxygen/chapters/optimize_performance.doxy

@@ -59,7 +59,9 @@ implicit dependencies on that data.
 
 In the same vein, accumulation of results in the same data can become a
 bottleneck. The use of the mode ::STARPU_REDUX permits to optimize such
-accumulation (see \ref Data_reduction).
+accumulation (see \ref Data_reduction). To a lesser extent, the use of
+the flag ::STARPU_COMMUTE keeps the bottleneck, but at least permits
+the accumulation to happen in any order.
 
 Applications often need a data just for temporary results.  In such a case,
 registration can be made without an initial value, for instance this produces a vector data:

doc/doxygen/chapters/scheduling_context_hypervisor.doxy

@@ -123,8 +123,10 @@ The number of flops to be executed by a context are passed as
  (<c>sc_hypervisor_register_ctx(sched_ctx_id, flops)</c>) and the one
  to be executed by each task are passed when the task is submitted.
  The corresponding field is starpu_task::flops and the corresponding
- macro in the function starpu_insert_task() ::STARPU_FLOPS. When the
- task is executed the resizing process is triggered.
+ macro in the function starpu_insert_task() ::STARPU_FLOPS
+ (<b>Caution</b>: but take care of passing a double, not an integer,
+ otherwise parameter passing will be bogus). When the task is executed
+ the resizing process is triggered.
 
 \code{.c}
 task.flops = 100;