Improve docs

Author: efaulhaber

benchmarks/run_benchmarks.jl

@@ -5,24 +5,36 @@ using BenchmarkTools
 include("../test/point_cloud.jl")
 
 """
-    plot_benchmarks(benchmark, n_points_per_dimension, iterations;
-                    seed = 1, perturbation_factor_position = 1.0,
-                    parallel = true, title = "")
+    run_benchmarks(benchmark, n_points_per_dimension, iterations, neighborhood_searches;
+                   parallelization_backend = PolyesterBackend(),
+                   names = ["NeighborhoodSearch 1" "NeighborhoodSearch 2" ...],
+                   seed = 1, perturbation_factor_position = 1.0)
 
 Run a benchmark with several neighborhood searches multiple times for increasing numbers
-of points and plot the results.
+of points and return the results as `(n_particles_vec, times)`, where `n_particles_vec`
+is a vector containing the number of particles for each iteration and `times` is a matrix
+containing the runtimes for each neighborhood search and iteration.
+
+See also
+- [`plot_benchmark`](@ref) to plot the results,
+- [`run_benchmark_default`](@ref) to run the benchmark with the most commonly used
+  neighborhood search implementations,
+- [`run_benchmark_gpu`](@ref) to run the benchmark with all GPU-compatible neighborhood
+  search implementations.
 
 # Arguments
-- `benchmark`:              The benchmark function. See [`benchmark_count_neighbors`](@ref)
-                            and [`benchmark_n_body`](@ref).
+- `benchmark`:              The benchmark function. See [`benchmark_count_neighbors`](@ref),
+                            [`benchmark_n_body`](@ref), [`benchmark_wcsph`](@ref),
+                            [`benchmark_wcsph_fp32`](@ref) and [`benchmark_tlsph`](@ref).
 - `n_points_per_dimension`: Initial resolution as tuple. The product is the initial number
                             of points. For example, use `(100, 100)` for a 2D benchmark or
                             `(10, 10, 10)` for a 3D benchmark.
 - `iterations`:             Number of refinement iterations
 
 # Keywords
-- `parallel = true`:        Loop over all points in parallel
-- `title = ""`:             Title of the plot
+- `parallelization_backend = PolyesterBackend()`: Parallelization strategy to use. See
+                                                  [`@threaded`](@ref) for a list of available
+                                                  backends.
 - `seed = 1`:               Seed to perturb the point positions. Different seeds yield
                             slightly different point positions.
 - `perturbation_factor_position = 1.0`: Scale the point position perturbation by this factor.
@@ -33,12 +45,14 @@ of points and plot the results.
 ```julia
 include("benchmarks/benchmarks.jl")
 
-plot_benchmarks(benchmark_count_neighbors, (10, 10), 3)
+run_benchmark(benchmark_count_neighbors, (10, 10), 3,
+              [TrivialNeighborhoodSearch{2}(), GridNeighborhoodSearch{2}()])
+```
 """
 function run_benchmark(benchmark, n_points_per_dimension, iterations, neighborhood_searches;
-                       names = ["NeighborhoodSearch $i"
-                                for i in 1:length(neighborhood_searches)]',
                        parallelization_backend = PolyesterBackend(),
+                       names = ["Neighborhood search $i"
+                                for i in 1:length(neighborhood_searches)]',
                        seed = 1, perturbation_factor_position = 1.0)
     # Multiply number of points in each iteration (roughly) by this factor
     scaling_factor = 4
@@ -80,7 +94,34 @@ function run_benchmark(benchmark, n_points_per_dimension, iterations, neighborho
     return n_particles_vec, times
 end
 
-# Rum the benchmark with the most commonly used neighborhood search implementations
+"""
+    run_benchmark_default(benchmark, n_points_per_dimension, iterations; kwargs...)
+
+Shortcut to call [`run_benchmark`](@ref) with the most commonly used neighborhood search
+implementations:
+- `GridNeighborhoodSearch`
+- `GridNeighborhoodSearch` with `FullGridCellList`
+- `PrecomputedNeighborhoodSearch`
+
+# Arguments
+- `benchmark`:              The benchmark function. See [`benchmark_count_neighbors`](@ref),
+                            [`benchmark_n_body`](@ref), [`benchmark_wcsph`](@ref),
+                            [`benchmark_wcsph_fp32`](@ref) and [`benchmark_tlsph`](@ref).
+- `n_points_per_dimension`: Initial resolution as tuple. The product is the initial number
+                            of points. For example, use `(100, 100)` for a 2D benchmark or
+                            `(10, 10, 10)` for a 3D benchmark.
+- `iterations`:             Number of refinement iterations
+
+# Keywords
+See [`run_benchmark`](@ref) for a list of available keywords.
+
+# Examples
+```julia
+include("benchmarks/benchmarks.jl")
+
+run_benchmark_default(benchmark_n_body, (10, 10), 3)
+```
+"""
 function run_benchmark_default(benchmark, n_points_per_dimension, iterations; kwargs...)
     NDIMS = length(n_points_per_dimension)
     min_corner = 0.0f0 .* n_points_per_dimension
@@ -102,7 +143,32 @@ function run_benchmark_default(benchmark, n_points_per_dimension, iterations; kw
                   neighborhood_searches; names, kwargs...)
 end
 
-# Rum the benchmark with all GPU-compatible neighborhood search implementations
+"""
+    run_benchmark_gpu(benchmark, n_points_per_dimension, iterations; kwargs...)
+
+Shortcut to call [`run_benchmark`](@ref) with all GPU-compatible neighborhood search
+implementations:
+- `GridNeighborhoodSearch` with `FullGridCellList`
+
+# Arguments
+- `benchmark`:              The benchmark function. See [`benchmark_count_neighbors`](@ref),
+                            [`benchmark_n_body`](@ref), [`benchmark_wcsph`](@ref),
+                            [`benchmark_wcsph_fp32`](@ref) and [`benchmark_tlsph`](@ref).
+- `n_points_per_dimension`: Initial resolution as tuple. The product is the initial number
+                            of points. For example, use `(100, 100)` for a 2D benchmark or
+                            `(10, 10, 10)` for a 3D benchmark.
+- `iterations`:             Number of refinement iterations
+
+# Keywords
+See [`run_benchmark`](@ref) for a list of available keywords.
+
+# Examples
+```julia
+include("benchmarks/benchmarks.jl")
+
+run_benchmark_gpu(benchmark_n_body, (10, 10), 3)
+```
+"""
 function run_benchmark_gpu(benchmark, n_points_per_dimension, iterations; kwargs...)
     NDIMS = length(n_points_per_dimension)
 
@@ -120,6 +186,27 @@ function run_benchmark_gpu(benchmark, n_points_per_dimension, iterations; kwargs
                   neighborhood_searches; names, kwargs...)
 end
 
+"""
+    plot_benchmark(n_particles_vec, times; kwargs...)
+
+Plot the results of a benchmark run with [`run_benchmark`](@ref).
+Note that the arguments are the outputs of that function.
+
+# Arguments
+- `n_particles_vec`: Vector containing the number of particles for each iteration.
+- `times`:           Matrix containing the runtimes for each neighborhood search and iteration.
+
+# Keywords
+Keyword arguments are passed to `Plots.plot`. For example, use `title = "My title"`.
+
+# Examples
+```julia
+include("benchmarks/benchmarks.jl")
+
+n_particles_vec, times = run_benchmark_default(benchmark_count_neighbors, (10, 10), 3)
+plot_benchmark(n_particles_vec, times; title = "Count neighbors benchmark")
+```
+"""
 function plot_benchmark(n_particles_vec, times; kwargs...)
     function format_n_particles(n)
         if n >= 1_000_000