From 90ebbe0f6494e65a78654e76628c4befcf86b71f Mon Sep 17 00:00:00 2001
From: Hans Dembinski <hans.dembinski@gmail.com>
Date: Mon, 15 Nov 2021 09:24:22 +0100
Subject: [PATCH] improved doxygen docs

---
 doc/doxygen_postprocessing.py           | 10 ++++++++--
 include/boost/histogram/axis/option.hpp |  4 ++++
 include/boost/histogram/axis/traits.hpp | 10 +++++-----
 include/boost/histogram/fwd.hpp         | 16 ++++++++--------
 4 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/doc/doxygen_postprocessing.py b/doc/doxygen_postprocessing.py
index eb475d43..c41aa6e2 100644
--- a/doc/doxygen_postprocessing.py
+++ b/doc/doxygen_postprocessing.py
@@ -23,11 +23,11 @@ def select(condition, *tags):
 
 def is_detail(x):
     if x.text is not None:
-        if "detail" in x.text:
+        if "detail" in x.text.lower():
             return True
         m = re.match(r"(?:typename)? *([A-Za-z0-9_\:]+)", x.text)
         if m is not None:
-            s = m.group(1)
+            s = m.group(1).lower()
             if s.startswith("detail") or s.endswith("_impl"):
                 x.text = s
                 return True
@@ -103,6 +103,12 @@ def item_sorter(elem):
     else:
         log("removing unnamed template parameter from", parent.tag, name)
 
+# hide macros with detail in the name
+for item in select(lambda x: "DETAIL" in x.get("name").split("_"), "macro"):
+    parent = parent_map[item]
+    parent.remove(item)
+    log("removing macro", item.get("name"))
+
 # replace any type with "detail" in its name with "unspecified"
 for item in select(is_detail, "type"):
     log("replacing", '"%s"' % item.text, 'with "unspecified"')
diff --git a/include/boost/histogram/axis/option.hpp b/include/boost/histogram/axis/option.hpp
index 920aeef4..e71999b9 100644
--- a/include/boost/histogram/axis/option.hpp
+++ b/include/boost/histogram/axis/option.hpp
@@ -57,7 +57,11 @@ constexpr auto operator-(bitset<B1>, bitset<B2>) {
   @tparam Pos position of the bit in the set.
 */
 template <unsigned Pos>
+#ifndef BOOST_HISTOGRAM_DOXYGEN_INVOKED
 using bit = bitset<(1 << Pos)>;
+#else
+struct bit;
+#endif
 
 /// All options off.
 using none_t = bitset<0>;
diff --git a/include/boost/histogram/axis/traits.hpp b/include/boost/histogram/axis/traits.hpp
index 8e75918f..7e66d4eb 100644
--- a/include/boost/histogram/axis/traits.hpp
+++ b/include/boost/histogram/axis/traits.hpp
@@ -208,16 +208,16 @@ struct get_options;
   an axis type and represents compile-time boolean which is true or false, depending on
   whether the axis is inclusive or not.
 
+  An inclusive axis has a bin for every possible input value. In other words, all
+  possible input values always end up in a valid cell and there is no need to keep track
+  of input tuples that need to be discarded. A histogram which consists entirely of
+  inclusive axes can be filled more efficiently, which can be a factor 2 faster.
+
   An axis with underflow and overflow bins is always inclusive, but an axis may be
   inclusive under other conditions. The meta-function checks for the method `constexpr
   static bool inclusive()`, and uses the result. If this method is not present, it uses
   get_options<Axis> and checks whether the underflow and overflow bits are present.
 
-  An inclusive axis has a bin for every possible input value. A histogram which consists
-  only of inclusive axes can be filled more efficiently, since input values always
-  end up in a valid cell and there is no need to keep track of input tuples that need to
-  be discarded.
-
   @tparam Axis axis type
 */
 template <class Axis>
diff --git a/include/boost/histogram/fwd.hpp b/include/boost/histogram/fwd.hpp
index 4826ab3e..1b5fa014 100644
--- a/include/boost/histogram/fwd.hpp
+++ b/include/boost/histogram/fwd.hpp
@@ -150,14 +150,14 @@ class BOOST_ATTRIBUTE_NODISCARD histogram;
 
 namespace detail {
 
-/* Most of the histogram code is generic and works for any number of axes. Buffers with a
- * fixed maximum capacity are used in some places, which have a size equal to the rank of
- * a histogram. The buffers are statically allocated to improve performance, which means
- * that they need a preset maximum capacity. 32 seems like a safe upper limit for the rank
- * (you can nevertheless increase it here if necessary): the simplest non-trivial axis has
- * 2 bins; even if counters are used which need only a byte of storage per bin, 32 axes
- * would generate of 4 GB.
- */
+/*
+ Most of the histogram code is generic and works for any number of axes. Buffers with a
+ fixed maximum capacity are used in some places, which have a size equal to the rank of
+ a histogram. The buffers are allocated from the stack to improve performance, which
+ means in C++ that they need a preset maximum capacity. 32 seems like a safe upper limit
+ for the rank. You can nevertheless increase it with the compile-time flag
+ BOOST_HISTOGRAM_DETAIL_AXES_LIMIT, if necessary.
+*/
 #ifndef BOOST_HISTOGRAM_DETAIL_AXES_LIMIT
 #define BOOST_HISTOGRAM_DETAIL_AXES_LIMIT 32
 #endif