diff --git a/include/hpcombi/arch.hpp b/include/hpcombi/arch.hpp
index eaf9da6..cb395c2 100644
--- a/include/hpcombi/arch.hpp
+++ b/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_
 
diff --git a/include/hpcombi/bmat8.hpp b/include/hpcombi/bmat8.hpp
index cb789fa..15b1230 100644
--- a/include/hpcombi/bmat8.hpp
+++ b/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_
diff --git a/include/hpcombi/bmat8_impl.hpp b/include/hpcombi/bmat8_impl.hpp
index 0bc1529..6d17585 100644
--- a/include/hpcombi/bmat8_impl.hpp
+++ b/include/hpcombi/bmat8_impl.hpp
@@ -19,8 +19,8 @@
 //  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)
 
diff --git a/include/hpcombi/builder.hpp b/include/hpcombi/builder.hpp
index f8cfeab..aa48d6e 100644
--- a/include/hpcombi/builder.hpp
+++ b/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_
 
diff --git a/include/hpcombi/debug.hpp b/include/hpcombi/debug.hpp
index 2844316..b3fdf94 100644
--- a/include/hpcombi/debug.hpp
+++ b/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_
 
diff --git a/include/hpcombi/epu8.hpp b/include/hpcombi/epu8.hpp
index a862344..0fd2598 100644
--- a/include/hpcombi/epu8.hpp
+++ b/include/hpcombi/epu8.hpp
@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief declaration of HPCombi::epu8 */
+
 #ifndef HPCOMBI_EPU8_HPP_
 #define HPCOMBI_EPU8_HPP_
 
diff --git a/include/hpcombi/epu8_impl.hpp b/include/hpcombi/epu8_impl.hpp
index 69b0035..a143b81 100644
--- a/include/hpcombi/epu8_impl.hpp
+++ b/include/hpcombi/epu8_impl.hpp
@@ -19,8 +19,8 @@
 
 // NOLINT(build/header_guard)
 
-// This is the implementation part of epu8.hpp this should be seen as
-// implementation details and should not be included directly.
+/** @file
+@brief implementation of epu8.hpp ; this file should not be included directly. */
 
 #include <initializer_list>
 #include <iostream>
diff --git a/include/hpcombi/hpcombi.hpp b/include/hpcombi/hpcombi.hpp
index 74286f7..352c10d 100644
--- a/include/hpcombi/hpcombi.hpp
+++ b/include/hpcombi/hpcombi.hpp
@@ -17,6 +17,10 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief Main entry point; includes the API files: bmat8.hpp, perm16.hpp, etc
+and also debug.hpp, epu8.hpp, etc.*/
+
 #ifndef HPCOMBI_HPCOMBI_HPP_
 #define HPCOMBI_HPCOMBI_HPP_
 
diff --git a/include/hpcombi/perm16.hpp b/include/hpcombi/perm16.hpp
index bd83ea1..a412637 100644
--- a/include/hpcombi/perm16.hpp
+++ b/include/hpcombi/perm16.hpp
@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief declaration of HPCombi::PTransf16, HPCombi::Transf16, HPCombi::PPerm16 and HPCombi::Perm16. */
+
 #ifndef HPCOMBI_PERM16_HPP_
 #define HPCOMBI_PERM16_HPP_
 
diff --git a/include/hpcombi/perm16_impl.hpp b/include/hpcombi/perm16_impl.hpp
index 544b8a0..5c4d102 100644
--- a/include/hpcombi/perm16_impl.hpp
+++ b/include/hpcombi/perm16_impl.hpp
@@ -19,12 +19,10 @@
 
 // NOLINT(build/header_guard)
 
-namespace HPCombi {
-
-///////////////////////////////////////////////////////////////////////////////
-// Implementation part for inline functions  //////////////////////////////////
-///////////////////////////////////////////////////////////////////////////////
+/** @file
+@brief implementation of perm16.hpp ; this file should not be included directly. */
 
+namespace HPCombi {
 inline PTransf16::PTransf16(std::initializer_list<uint8_t> il)
     : Vect16(Epu8.id()) {
     HPCOMBI_ASSERT(il.size() <= 16);
diff --git a/include/hpcombi/perm_generic.hpp b/include/hpcombi/perm_generic.hpp
index b48be21..b641abd 100644
--- a/include/hpcombi/perm_generic.hpp
+++ b/include/hpcombi/perm_generic.hpp
@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief declaration of HPCombi::PermGeneric */
+
 #ifndef HPCOMBI_PERM_GENERIC_HPP_
 #define HPCOMBI_PERM_GENERIC_HPP_
 
diff --git a/include/hpcombi/perm_generic_impl.hpp b/include/hpcombi/perm_generic_impl.hpp
index 9930e0b..5369387 100644
--- a/include/hpcombi/perm_generic_impl.hpp
+++ b/include/hpcombi/perm_generic_impl.hpp
@@ -19,6 +19,10 @@
 
 // NOLINT(build/header_guard)
 
+/** @file
+@brief implementation of perm_generic.hpp ;
+this file should not be included directly. */
+
 namespace HPCombi {
 
 template <size_t Size, typename Expo>
diff --git a/include/hpcombi/power.hpp b/include/hpcombi/power.hpp
index 06a9349..eb621c4 100644
--- a/include/hpcombi/power.hpp
+++ b/include/hpcombi/power.hpp
@@ -18,23 +18,23 @@
 //****************************************************************************//
 
 /** @file
- * @brief Generic compile time power
- *
- * The goal of this file is to be able to write expressions such as @c
- * pow<23>(2.5) or @c pow<n>(x) where the first expression is entirely
- * computed as compile time and the second one is expanded also as compile
- * time to a O(log n) long sequence of multiplication. Furthermore such
- * expression not only works for numbers for for any type where there is a
- * neutral element and an associative (non necessarily commutative) product,
- * namely what mathematicians call \e monoids. These include for example,
- * strings where the neutral element is the empty string and the product is
- * the concatenation.
- *
- * see HPCombi::power_helper::Monoid<std::string>
- *
- * @example stringmonoid.cpp
- * This is an example of how to use pow with a non numerical Monoid.
- */
+@brief Generic compile-time exponentiation algorithm.
+
+The goal of this file is to be able to write expressions such as @c
+pow<23>(2.5) or @c pow<n>(x) where the first expression is entirely
+computed as compile time and the second one is expanded also as compile
+time to a O(log n) long sequence of multiplication. Furthermore such
+expression not only works for numbers for for any type where there is a
+neutral element and an associative (non necessarily commutative) product,
+namely what mathematicians call \e monoids. These include for example,
+strings where the neutral element is the empty string and the product is
+the concatenation.
+
+see HPCombi::power_helper::Monoid<std::string>
+
+@example stringmonoid.cpp
+This is an example of how to use pow with a non numerical Monoid.
+*/
 
 #ifndef HPCOMBI_POWER_HPP_
 #define HPCOMBI_POWER_HPP_
diff --git a/include/hpcombi/vect16.hpp b/include/hpcombi/vect16.hpp
index 14be7a2..251167c 100644
--- a/include/hpcombi/vect16.hpp
+++ b/include/hpcombi/vect16.hpp
@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief HPCombi::Vect16 */
+
 #ifndef HPCOMBI_VECT16_HPP_
 #define HPCOMBI_VECT16_HPP_
 
diff --git a/include/hpcombi/vect_generic.hpp b/include/hpcombi/vect_generic.hpp
index 767512d..fa89254 100644
--- a/include/hpcombi/vect_generic.hpp
+++ b/include/hpcombi/vect_generic.hpp
@@ -17,6 +17,9 @@
 //  with HP-Combi. If not, see <https://www.gnu.org/licenses/>.               //
 //****************************************************************************//
 
+/** @file
+@brief HPCombi::VectGeneric */
+
 #ifndef HPCOMBI_VECT_GENERIC_HPP_
 #define HPCOMBI_VECT_GENERIC_HPP_