Doc (#44)

BUILDING.md

@@ -18,7 +18,7 @@ tests, experiments, examples, or benchmarks.
 
 - [optional] : Google `sparsehash/dense_hash_map` and/or `sparsehash/dense_hash_set`.
 
-- [optional] Doxygen for generating the API documentation (in progress).
+- [optional] Doxygen for generating the API documentation (in [build/doc/html/index.html](build/doc/html/index.html)).
 
 ## Building
 

README.md

@@ -2,10 +2,9 @@
 High Performance Combinatorics in C++ using vector instructions v1.0.1
 
 HPCombi is a C++17 header-only library using the SSE and AVX instruction sets,
-and some equivalents, for very fast manipulation of combinatorial objects such
-as transformations, permutations, and boolean matrices of small size. The goal
-of this project is to implement various new algorithms and benchmark them on
-various compiler and architectures.
+and some equivalents, for very fast manipulation of small combinatorial objects
+such as transformations, permutations, and boolean matrices. HPCombi implements
+new algorithms and benchmarks them on various compilers and architectures.
 
 HPCombi was initially designed using the SSE and AVX instruction sets, and did
 not work on machines without these instructions (such as ARM). From v1.0.1
@@ -25,12 +24,12 @@ other processors too.
 
 - Reinis Cirpons <[email protected]> : CI
 - Finn Smith <[email protected]> : discussions + BMat8 reference code
-- Viviane Pons : algorithms discussions
+- Viviane Pons <[email protected]> : algorithms discussions
 - Daniel Vanzo <[email protected]> : GPU experiments
 
 ## Documentation
 
-- The Doxygen auto generated [API](https://libsemigroups.github.io/HPCombi/)
+- See the [Doxygen generated doc](https://libsemigroups.github.io/HPCombi/)
 
 ## Thanks
 

TODO.txt

@@ -2,5 +2,6 @@
 - https://cmake.org/Wiki/CMake:How_To_Write_Platform_Checks
 - https://stackoverflow.com/questions/11944060/how-to-detect-target-architecture-using-cmake
 
-
 Add method data in perm16 and perm_generic
+
+Document examples. Eg for each file foo.cpp in examples/, add "@example foo.cpp" in a relevant file of include/hpcombi/.

doc.html

@@ -0,0 +1 @@
+build/doc/html/index.html

doc/Doxyfile.in

@@ -934,8 +934,7 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = ${CMAKE_SOURCE_DIR}/include/hpcombi \
-                         ${CMAKE_SOURCE_DIR}/examples \
-                         ${CMAKE_SOURCE_DIR}/README.md
+                         ${CMAKE_SOURCE_DIR}/examples
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1101,7 +1100,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = ${CMAKE_SOURCE_DIR}/README.md
+USE_MDFILE_AS_MAINPAGE =
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common

include/hpcombi/arch.hpp

@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief check the required compiler flags for SSE-4.1 */
+
 #ifndef HPCOMBI_ARCH_HPP_
 #define HPCOMBI_ARCH_HPP_
 

include/hpcombi/bmat8.hpp

@@ -19,7 +19,8 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
-// This file contains a declaration of fast boolean matrices up to dimension 8.
+/** @file
+@brief declaration of HPCombi::BMat8 */
 
 #ifndef HPCOMBI_BMAT8_HPP_
 #define HPCOMBI_BMAT8_HPP_
@@ -40,15 +41,17 @@
 
 namespace HPCombi {
 
-//! Class for fast boolean matrices of dimension up to 8 x 8
-//!
-//! The methods for these small matrices over the boolean semiring
-//! are more optimised than the generic methods for boolean matrices.
-//! Note that all BMat8 are represented internally as an 8 x 8 matrix;
-//! any entries not defined by the user are taken to be 0. This does
-//! not affect the results of any calculations.
-//!
-//! BMat8 is a trivial class.
+/** Boolean matrices of dimension up to 8×8, stored as a single uint64;
+isomorph to binary relations with methods for composition.
+
+The methods for these small matrices over the boolean semiring
+are more optimised than the generic methods for boolean matrices.
+Note that all BMat8 are represented internally as an 8×8 matrix;
+any entries not defined by the user are taken to be 0. This does
+not affect the results of any calculation.
+
+BMat8 is a trivial class.
+*/
 class BMat8 {
  public:
     //! A default constructor.

include/hpcombi/bmat8_impl.hpp

@@ -19,8 +19,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
-// This file contains an implementation of fast boolean matrices up to
-// dimension 8 x 8.
+/** @file
+@brief implementation of bmat8.hpp ; this file should not be included directly.
+*/
 
 // NOLINT(build/header_guard)
 

include/hpcombi/builder.hpp

@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief HPCombi::TPUBuild and casts from HPCombi::TPU */
+
 #ifndef HPCOMBI_BUILDER_HPP_
 #define HPCOMBI_BUILDER_HPP_
 
@@ -30,8 +33,11 @@
 
 namespace HPCombi {
 
-/** Class for factory object associated to a SIMD packed unsigned integers.
+/** Given a transformation from 0..15 → 0..15,
+ * build at compile-time the array representing the transformation.
+ *
  * @details
+ * Class for factory object associated to a SIMD packed unsigned integers.
  * The main purpose of this class is to be able to construct in a \c constexpr
  * way various instances of the \c TPU SIMD vector type. The behavior of
  * an instance of \c TPUBuild<TPU> is designed to mimic the behavior of \c TPU

include/hpcombi/debug.hpp

@@ -18,6 +18,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief defines the macro \c HPCOMBI_ASSERT */
+
 #ifndef HPCOMBI_DEBUG_HPP_
 #define HPCOMBI_DEBUG_HPP_