doc fixes

Author: HDembinski

doc/benchmarks.qbk

@@ -9,14 +9,14 @@ The following plot shows results of a benchmark on a 9 GHz Macbook Pro. Random n
 [variablelist Plot legend:
 	[[root] [[@https://root.cern.ch ROOT classes] (`TH1I` for 1D, `TH3I` for 3D and `THnI` for 6D)]]
 	[[py:numpy] [numpy functions ([python]`numpy.histogram` for 1D, `numpy.histogramdd` for 2D, 3D, and 6D)]]
-	[[py:hd_sd] [[classref boost::histogram::dynamic_histogram] with [classref boost::histogram::adaptive_storage], called from Python]]
-	[[hs_ss] [[classref boost::histogram::static_histogram] with [classref boost::histogram::array_storage<int>]]]
-	[[hs_sd] [[classref boost::histogram::static_histogram] with [classref boost::histogram::adaptive_storage]]]
-	[[hd_ss] [[classref boost::histogram::dynamic_histogram] with [classref boost::histogram::array_storage<int>]]]
-	[[hd_sd] [[classref boost::histogram::dynamic_histogram] with [classref boost::histogram::adaptive_storage]]]
+	[[py:hd_sd] [[funcref boost::histogram::make_dynamic_histogram dynamic histogram] with [classref boost::histogram::adaptive_storage], called from Python]]
+	[[hs_ss] [[funcref boost::histogram::make_static_histogram static histogram] with [classref boost::histogram::array_storage<int>]]]
+	[[hs_sd] [[funcref boost::histogram::make_static_histogram static histogram] with [classref boost::histogram::adaptive_storage]]]
+	[[hd_ss] [[funcref boost::histogram::make_dynamic_histogram dynamic histogram] with [classref boost::histogram::array_storage<int>]]]
+	[[hd_sd] [[funcref boost::histogram::make_dynamic_histogram dynamic histogram] with [classref boost::histogram::adaptive_storage]]]
 ]
 
-[classref boost::histogram::static_histogram] is always faster than [classref boost::histogram::dynamic_histogram] and safer to use, as more checks are done at compile time. It is recommended when working in C++ only. [classref boost::histogram::adaptive_storage] is faster than [classref boost::histogram::array_storage] for histograms with many bins, because it uses the cache more effectively due to its smaller memory consumption per bin. If the number of bins is small, it is slower because of overhead of handling memory in a dynamic way.
+A [classref boost::histogram::make_static_histogram static histogram] is always faster than [classref boost::histogram::make_dynamic_histogram dynamic histogram] and safer to use, as more checks are done at compile time. It is recommended when working in C++ only. [classref boost::histogram::adaptive_storage] is faster than [classref boost::histogram::array_storage] for histograms with many bins, because it uses the cache more effectively due to its smaller memory consumption per bin. If the number of bins is small, it is slower because of overhead of handling memory in a dynamic way.
 
 The histograms in this library are mostly faster than the competition, in some cases by a factor of 2. Simultaneously they are more flexible, since binning strategies can be customised. The Python-wrapped histogram is slower than numpy's own specialized function for 1D, but beats numpy's multi-dimensional histogramming function by a factor 2 to 3.
 

doc/concepts.qbk

@@ -8,7 +8,7 @@ An `axis_type` converts input values into bin indices.
 
 An `axis_type` is required to:
 
-* derive publically from [classref boost::histogram::axis::axis_base] or [classref boost::histogram::axis::axis_base_uoflow]
+* derive publically from [classref boost::histogram::axis::labeled_base] and [classref boost::histogram::axis::iterator_mixin]
 * be default/copy/move constructable
 * be copy/move assignable
 * be equal comparable
@@ -37,6 +37,7 @@ A `storage_type` is required to:
 * be default/copy/move constructable
 * be copy/move assignable
 * be equal comparable
+* have a nested type `allocator_type`
 * have a nested type `element_type`, which represent the bin count
 * have a nested type `const_reference`, its const reference version
 * have a constructor `storage_type(std::size_t n)`, which prepares the storage of `n` bins.

doc/guide.qbk

@@ -61,7 +61,7 @@ In addition to the required parameters for an axis, you can assign an optional l
 
 Without the labels it would be difficult to remember which axis was covering which quantity, because they look the same otherwise. Labels are the only axis property that can be changed later. Axes objects with different label do not compare equal with `operator==`.
 
-By default, additional under- and overflow bins are added automatically for each axis where that makes sense. If you create an axis with 20 bins, the histogram will actually have 22 bins along that axis. The two extra bins are generally very good to have, as explained in [link histogram.rationale.uoflow the rationale]. If you are certain that the input cannot exceed the axis range, you can disable the extra bins to save memory. This is done by passing the enum value [enumref boost::histogram::axis::uoflow uoflow::off] to the axis constructor:
+By default, additional under- and overflow bins are added automatically for each axis where that makes sense. If you create an axis with 20 bins, the histogram will actually have 22 bins along that axis. The two extra bins are generally very good to have, as explained in [link histogram.rationale.uoflow the rationale]. If you are certain that the input cannot exceed the axis range, you can disable the extra bins to save memory. This is done by passing the enum value [enumref boost::histogram::axis::uoflow_type uoflow_type::off] to the axis constructor:
 
 [import ../examples/guide_axis_with_uoflow_off.cpp]
 [guide_axis_with_uoflow_off]
@@ -95,7 +95,7 @@ Why weighted increments are sometimes useful, especially in a scientific context
 
 After the histogram has been filled, you want to access the counts per bin at some point. You may want to visualize the counts, or compute some quantities like the mean from the data distribution approximated by the histogram.
 
-To access each bin, you use a multi-dimensional index, which consists of a sequence of bin indices for each axes in order. You can use this index to access the value for each and the variance estimate, using the method `histogram::bin(...)`. It accepts integral indices, one for each axis of the histogram, and returns the associated bin counter type. The bin counter type then allows you to access the count value and its variance.
+To access each bin, you use a multi-dimensional index, which consists of a sequence of bin indices for each axes in order. You can use this index to access the value for each and the variance estimate, using the method `histogram::at(...)` (in analogy to `std::vector::at`). It accepts integral indices, one for each axis of the histogram, and returns the associated bin counter type. The bin counter type then allows you to access the count value and its variance.
 
 The calls are demonstrated in the next example.
 

examples/guide_access_bin_counts.cpp

@@ -28,7 +28,7 @@ int main() {
             << std::endl;
   // prints: 1 4 9 16
 
-  // you can also make a copy of the type that holds the bin count
+  // this is more efficient when you want to query value and variance
   auto c11 = h.at(1, 1);
   std::cout << c11.value() << " " << c11.variance() << std::endl;
   // prints: 4 16
@@ -39,11 +39,24 @@ int main() {
   std::cout << h.at(idx).value() << std::endl;
   // prints: 2
 
-  // histogram also provides extended iterators
+  // histogram also provides bin iterators
   auto sum = std::accumulate(h.begin(), h.end(),
                              typename decltype(h)::element_type(0));
   std::cout << sum.value() << " " << sum.variance() << std::endl;
   // prints: 10 30
+
+  // bin iterators are fancy iterators with extra methods
+  for (auto it = h.begin(), end = h.end(); it != end; ++it) {
+    const auto x = *it;
+    std::cout << it.idx(0) << " " << it.idx(1) << ": "
+              << x.value() << " " << x.variance() << std::endl;
+  }
+  // prints: (iteration order is an implementation detail, don't rely on it)
+  // 0 0: 1 1
+  // 1 0: 3 9
+  // ...
+  // 2 -1: 0 0
+  // -1 -1: 0 0
 }
 
 //]

examples/guide_fill_histogram.cpp

@@ -24,9 +24,9 @@ int main() {
   // functional-style processing is also supported
   std::vector<std::pair<int, double>> input_data{
       {0, 1.2}, {2, 3.4}, {4, 5.6}};
-  // Note that std::for_each takes the functor by value, thus it makes a
-  // potentially expensive copy of your histogram. Passing freshly created
-  // histograms is ok, though, because of return-value-optimization
+  // std::for_each takes the functor by value, thus it potentially makes
+  // expensive copies of the histogram, but modern compilers are usually smart
+  // enough to avoid the superfluous copies
   auto h2 =
       std::for_each(input_data.begin(), input_data.end(),
                     bh::make_static_histogram(bh::axis::regular<>(8, 0, 4),

examples/guide_make_dynamic_histogram.cpp

@@ -19,7 +19,7 @@ int main() {
 
 
   // make_dynamic_histogram copies axis objects; to instead move the whole axis
-  // vector into the histogram, create a histogram instance directly like so
+  // vector into the histogram, create a histogram instance directly
   auto h2 = bh::histogram<decltype(v)>(std::move(v));
 
   // do something with h2