From ab3f7140a9a6e184fc0b5b8cef3a73dfca7e388d Mon Sep 17 00:00:00 2001
From: Simon Giraudot <simon.giraudot@geometryfactory.com>
Date: Thu, 5 Mar 2020 10:41:13 +0100
Subject: [PATCH] Document parallel build

---
 Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h | 10 ++++++++++
 .../doc/Spatial_searching/Spatial_searching.txt        |  7 +++++++
 2 files changed, 17 insertions(+)

diff --git a/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h b/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h
index 9a86c03e7fe..91292fe82ad 100644
--- a/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h
+++ b/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h
@@ -115,7 +115,17 @@ at the first call to a query or removal member function. You can call
 `build()` explicitly to ensure that the next call to
 query functions will not trigger the reconstruction of the
 data structure.
+
+\tparam ConcurrencyTag enables sequential versus parallel
+algorithm. Possible values are `Sequential_tag`, `Parallel_tag`, and
+`Parallel_if_available_tag`. This template parameter is optional:
+calling `build()` without specifying the concurrency tag will result
+in `Sequential_tag` being used. If `build()` is not called by the user
+but called implicitly at the first call to a query or removal member
+function, `Sequential_tag` is also used.
+
 */
+template <typename ConcurrencyTag>
 void build();
 
 /*!
diff --git a/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt b/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt
index fb7fa79d487..bfd9058ffd7 100644
--- a/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt
+++ b/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt
@@ -480,6 +480,13 @@ to the nearest nodes exceeds the distance to the nearest point found
 with a factor 1/ (1+\f$ \epsilon\f$). Priority search supports next
 neighbor search, standard search does not.
 
+In order to speed-up the construction of the `kd` tree, the child
+branches of each internal node can be computed in parallel, by calling
+`Kd_tree::build<CGAL::Parallel_tag>()`. On a quad-core processor, the
+parallel construction is experimentally 2 to 3 times faster than the
+sequential version, depending on the point cloud. The parallel version
+requires the executable to be linked against the <a href="https://www.threadingbuildingblocks.org">Intel TBB library</a>.
+
 In order to speed-up the internal distance computations in nearest
 neighbor searching in high dimensional space, the approximate
 searching package supports orthogonal distance computation. Orthogonal distance