getting started 04 update (#213)

doc/getting_started.qbk

@@ -57,7 +57,7 @@ The library was designed to be very flexible and modular. The modularity is used
 
 [section Standard library algorithms]
 
-The library was designed to work well with the C++ standard library. Here is an example on how to get the maximum highest count in a 3d histogram with `std::max_element`.
+The library was designed to work well with the C++ standard library. Here is an example on how to get the most common color from an image, using a 3d histogram and `std::max_element`.
 
 [import ../examples/getting_started_listing_04.cpp]
 [getting_started_listing_04]

examples/getting_started_listing_04.cpp

@@ -20,7 +20,8 @@ int main() {
 
   /*
     We make a 3d histogram for color values (r, g, b) in an image. We assume the values
-    are of type char. The value range then is [0, 256).
+    are of type char. The value range then is [0, 256). The integer axis is perfect for
+    color values.
   */
   auto h = make_histogram(
     axis::integer<>(0, 256, "r"),
@@ -36,16 +37,16 @@ int main() {
   h(0, 1, 0);
 
   /*
-    Now let's say we want to know which color is most common. We can use std::max_element on an
+    Now let's say we want to know which color is most common. We can use std::max_element
-    indexed range for that.
+    on an indexed range for that.
   */
   auto ind = indexed(h);
   auto max_it = std::max_element(ind.begin(), ind.end());
 
   /*
-    max_it is the iterator to the maximum counter. This is the special iterator from indexed_range,
+    max_it is a special iterator to the histogram cell with the highest count.
-    you can use it to access the cell index as well and the bin values. You need to
+    This iterator allows one to access the cell value, bin indices, and bin values.
-    double-dereference it to get to the cell count.
+    You need to twice dereference it to get to the cell value.
   */
   std::ostringstream os;
   os << boost::format("count=%i rgb=(%i, %i, %i)")

include/boost/histogram/indexed.hpp

@@ -55,16 +55,17 @@ public:
   class iterator;
   using range_iterator = iterator; ///< deprecated
 
-  /** Pointer-like class to access value and index of current cell.
+  /** Lightweight view to access value and index of current cell.
 
-    Its methods provide access to the current indices and bins and it acts like a pointer
+    The methods provide access to the current cell indices and bins. It acts like a
-    to the cell value. To interoperate with the algorithms of the standard library, the
+    pointer to the cell value, and in a limited way also like a reference. To interoperate
-    accessor is implicitly convertible to a cell value. Assignments and comparisons are
+    with the algorithms of the standard library, the accessor is implicitly convertible to
-    passed through to the cell. The accessor is coupled to its parent iterator. Moving the
+    a cell value. Assignments and comparisons are passed through to the cell. An accessor
-    parent iterator forward also updates the linked accessor. Accessors are not copyable.
+    is coupled to its parent indexed_range::iterator. Moving the parent iterator
-    They cannot be stored in containers, but range_iterators can be stored.
+    forward also updates the linked accessor. Accessors are not copyable. They cannot be
+    stored in containers, but indexed_range::iterator can be stored.
   */
-  class accessor : detail::mirrored<accessor, void> {
+  class BOOST_ATTRIBUTE_NODISCARD accessor : detail::mirrored<accessor, void> {
   public:
     /// Array-like view into the current multi-dimensional index.
     class index_view {