Reduce the number of warnings produced by make doc (libsemigroups#681)

* Balance adapter groups

* Ignore formatter

* Fix \ref at end of line

* Fix dot function links

* Add class for ref

* Fix template type in ref

* Fix param not found

* fix param not documented

* Add BMat8 doc

* Add punctuation to doc

* Don't parse formatters

* Fix bad references

* Fix more bad references

* Manually exclude files from doxygen

* Add more ifndef doxygen

* Fix spacing

* Add presentation deduction guides

* format

* linting

* Remove ref to libsemigroups::detail::Rule

* Remove \ref for HPCombi::Class

These are classes that we don't own, and hence
don't have the documentation for.

* Fix doc warnings in Konieczny

* Fix more doc warnings

* Document Node and Edge

* Document call operators in word range

* Document is_standardized

* Document throw_if function

* Fix some no docs

* Fix doxygen commands with line breaks

* Punctuation

* Add updated to-table

* spelling

Author: Joseph-Edwards

docs/Doxyfile

@@ -1112,7 +1112,23 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which Doxygen is
 # run.
 
-# EXCLUDE                = ../include/libsemigroups/detail/
+EXCLUDE                = ../include/libsemigroups/detail/bruidhinn-traits.hpp \
+                         ../include/libsemigroups/detail/citow.hpp \
+                         ../include/libsemigroups/detail/containers.hpp \
+                         ../include/libsemigroups/detail/felsch-graph.hpp \
+                         ../include/libsemigroups/detail/formatters.hpp \
+                         ../include/libsemigroups/detail/int-range.hpp \
+                         ../include/libsemigroups/detail/iterator.hpp \
+                         ../include/libsemigroups/detail/kambites-nf.hpp \
+                         ../include/libsemigroups/detail/multi-string-view.hpp \
+                         ../include/libsemigroups/detail/path-iterators.hpp \
+                         ../include/libsemigroups/detail/pool.hpp \
+                         ../include/libsemigroups/detail/report.hpp \
+                         ../include/libsemigroups/detail/stl.hpp \ 
+                         ../include/libsemigroups/detail/string.hpp \
+                         ../include/libsemigroups/detail/timer.hpp \
+                         ../include/libsemigroups/detail/uf.hpp \
+                         ../include/libsemigroups/detail/word-iterators.hpp
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

docs/pictures/to-table.svg

@@ -244,7 +244,7 @@ namespace libsemigroups {
     //! \sa ImageRightAction, ImageLeftAction
     using action_type = Func;
 
-    //! \brief Insertion operator
+    //! \brief Insertion operator.
     //!
     //! This member function allows Action objects to be inserted into an
     //! std::ostringstream.
@@ -257,7 +257,7 @@ namespace libsemigroups {
     operator<<(std::ostringstream&                                 os,
                Action<Elment, Pint, Fnc, Trits, LftOrRight> const& action);
 
-    //! \brief Insertion operator
+    //! \brief Insertion operator.
     //!
     //! This member function allows Action objects to be inserted into a
     //! std::ostream.
@@ -392,8 +392,8 @@ namespace libsemigroups {
     // Action - modifiers - public
     ////////////////////////////////////////////////////////////////////////
 
-    //! \brief Increase the capacity to a value that is greater or equal to \p
-    //! val.
+    //! \brief Increase the capacity to a value that is greater or equal to
+    //! \p val.
     //!
     //! Increase the capacity to a value that is greater or equal to \p val.
     //!
@@ -530,8 +530,8 @@ namespace libsemigroups {
     //! \param pos the index of a point.
     //!
     //! \returns
-    //! A \ref const_reference_point_type to the point in position \p
-    //! pos of the currently enumerated points.
+    //! A \ref const_reference_point_type to the point in position
+    //! \p pos of the currently enumerated points.
     //!
     //! \throws
     //! std::out_of_range if `!(pos < current_size())`.

include/libsemigroups/action.hpp

@@ -130,9 +130,9 @@ namespace libsemigroups {
   //! and/or `constexpr` also).
   //!
   //! The return value of the call operator ought to indicate the degree of a
-  //! `Element` instance which may or may not depend on the parameter \p
-  //! x. The degree of a permutation, for instance, would be the the number of
-  //! points it acts on, the degree of a matrix is its dimension, and so on.
+  //! `Element` instance which may or may not depend on the parameter
+  //! \p x. The degree of a permutation, for instance, would be the the number
+  //! of points it acts on, the degree of a matrix is its dimension, and so on.
   //! This is used, for example, by SchreierSimsTraits in some member functions
   //! to determine whether it is known *a priori* that a permutation does not
   //! belong to the object, because it acts on too many points.
@@ -412,7 +412,7 @@ namespace libsemigroups {
   //! * SchreierSimsTraits
   template <typename Value, typename = void>
   struct EqualTo {
-    //! \brief Compare \p x and \p y with std::equal_to
+    //! \brief Compare \p x and \p y with std::equal_to.
     //!
     //! This call operator compares \p x and \p y using std::equal_to with
     //! template parameter \c Value.
@@ -444,12 +444,12 @@ namespace libsemigroups {
   //! * SchreierSimsTraits
   template <typename Value, typename = void>
   struct Hash {
-    //! \brief Hash \p x using std::hash
+    //! \brief Hash \p x using std::hash.
     //!
     //! This call operator hashes \p x using std::hash with template parameter
     //! \c Value.
     //!
-    //! \param x the value to hash
+    //! \param x the value to hash.
     //!
     //! \returns A hash value for \p x, a value of type `size_t`.
     size_t operator()(Value const& x) const {
@@ -474,7 +474,7 @@ namespace libsemigroups {
   //! \par Used by KoniecznyTraits.
   template <typename T>
   struct Hash<std::vector<T>> {
-    //! \brief Hashes \p vec
+    //! \brief Hashes \p vec.
     //!
     //! This call operator hashes \p vec.
     //!
@@ -504,11 +504,11 @@ namespace libsemigroups {
   // TODO(later) What uses this?
   template <typename T, typename Hasher>
   struct Hash<std::vector<T>, Hasher> {
-    //! \brief Hashes \p vec
+    //! \brief Hashes \p vec.
     //!
     //! This call operator hashes \p vec.
     //!
-    //! \param vec the value to hash
+    //! \param vec the value to hash.
     //!
     //! \returns A hash value for \p vec, a value of type `size_t`.
     size_t operator()(std::vector<T> const& vec) const {
@@ -534,7 +534,7 @@ namespace libsemigroups {
   // TODO(later) What uses this?
   template <typename T, size_t N>
   struct Hash<std::array<T, N>> {
-    //! \brief Hashes \p ar
+    //! \brief Hashes \p ar.
     //!
     //! This call operator hashes \p ar.
     //!
@@ -565,7 +565,7 @@ namespace libsemigroups {
   // TODO(later) What uses this?
   template <typename S, typename T>
   struct Hash<std::pair<S, T>> {
-    //! \brief Hashes \p x
+    //! \brief Hashes \p x.
     //!
     //! This call operator hashes \p x.
     //!
@@ -595,7 +595,7 @@ namespace libsemigroups {
     //!
     //! This call operator hashes \p x.
     //!
-    //! \param x the value to hash
+    //! \param x the value to hash.
     //!
     //! \returns A hash value for \p x, a value of type `size_t`.
     size_t operator()(std::pair<size_t, size_t> const& x) const noexcept {
@@ -658,7 +658,7 @@ namespace libsemigroups {
   //! * SchreierSimsTraits
   template <typename Value, typename = void>
   struct Swap {
-    //! \brief Swap \p x and \p y
+    //! \brief Swap \p x and \p y.
     //!
     //! This call operator swaps \p x and \p y using std::swap.
     //!
@@ -677,9 +677,9 @@ namespace libsemigroups {
   //! This struct applies `ImageRightAction<Element, Point>` to every value in a
   //! container of type `Container`.
   //!
-  //! \tparam Element the type of the elements of the semigroup
-  //! \tparam Point the type of the points acted on
-  //! \tparam Container a container of Point
+  //! \tparam Element the type of the elements of the semigroup.
+  //! \tparam Point the type of the points acted on.
+  //! \tparam Container a container of Point.
   template <typename Element,
             typename Point,
             typename Container = std::vector<Point>>
@@ -722,8 +722,8 @@ namespace libsemigroups {
   //! This struct applies `OnTuples<Element, Point,
   //! Container>` to  a container of `Container` and then sorts it.
   //!
-  //! \tparam Element the type of elements
-  //! \tparam Point the type of the points acted on
+  //! \tparam Element the type of elements.
+  //! \tparam Point the type of the points acted on.
   //! \tparam Container a container of \p Point (defaults to std::vector with
   //! template parameter \c Point).
   // TODO(2) add a template param for sorting
@@ -745,8 +745,8 @@ namespace libsemigroups {
     //!
     //! \param res a container of \c Point (such as std::vector or std::array)
     //! to hold the result.
-    //! \param pt  a container of \c Point
-    //! \param p an element of type \c Element
+    //! \param pt  a container of \c Point.
+    //! \param p an element of type \c Element.
     //!
     //! \complexity
     //! `pt.size()` times the complexity of `ImageRightAction<Element,
@@ -760,15 +760,11 @@ namespace libsemigroups {
       std::sort(res.begin(), res.end());
     }
   };
-  //! @}
 
   /////////////////////////////////////////////////////////////////////
   // KONIECZNY THINGS
   /////////////////////////////////////////////////////////////////////
 
-  //! \addtogroup adapters_no_default_group
-  //! @{
-
   //! \brief Adapter for lambda functions.
   //!
   //! Defined in `adapters.hpp`.
@@ -925,6 +921,5 @@ namespace libsemigroups {
             typename       = void>
   struct Rank;
 
-  //! @}
 }  // namespace libsemigroups
 #endif  // LIBSEMIGROUPS_ADAPTERS_HPP_

include/libsemigroups/adapters.hpp

@@ -59,7 +59,7 @@ namespace libsemigroups {
 
   //! \ingroup aho_corasick_group
   //!
-  //! \brief For an implementation of the Aho-Corasick algorithm
+  //! \brief For an implementation of the Aho-Corasick algorithm.
   //!
   //! Defined in `aho-corasick.hpp`.
   //!
@@ -386,7 +386,7 @@ namespace libsemigroups {
     //! If \f$W\f$ does not correspond to a terminal node, then calling this
     //! function does nothing.
     //!
-    //! \tparam Iterator the type of the 1st and 2nd parameters
+    //! \tparam Iterator the type of the 1st and 2nd parameters.
     //! \param first iterator pointing to the first letter of the word to add.
     //! \param last one beyond the last letter of the word to add.
     //!
@@ -486,7 +486,7 @@ namespace libsemigroups {
       return w;
     }
 
-    //! \brief Find the signature of a node (in-place)
+    //! \brief Find the signature of a node (in-place).
     //!
     //! After validating \p i, this function performs the same as
     //! `signature_no_checks(w, i)`.
@@ -680,7 +680,7 @@ namespace libsemigroups {
     //! Constant.
     void validate_node_index(index_type i) const;
 
-    //! \brief Check if an index corresponds to a node currently in the trie
+    //! \brief Check if an index corresponds to a node currently in the trie.
     //!
     //! This function validates whether the given index \p i corresponds to an
     //! active node.
@@ -891,8 +891,8 @@ namespace libsemigroups {
     //! throws.
     //!
     //! \sa \ref traverse_word_no_checks(AhoCorasick const& ac, index_type
-    //! start, Iterator first, Iterator last), \ref
-    //! AhoCorasick::validate_active_node_index.
+    //! start, Iterator first, Iterator last),
+    //! \ref AhoCorasick::validate_active_node_index.
     template <typename Iterator>
     [[nodiscard]] index_type traverse_word(AhoCorasick const& ac,
                                            index_type         start,