Large range of doxygen improvements

19 files changed, 121 insertions, 26 deletions

diff --git a/Doxyfile b/Doxyfile
index 594a50ce..d8a07cca 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2031,7 +2031,10 @@ PREDEFINED             = __cplusplus=201402L DOXYGEN_SHOULD_SKIP_THIS=1
 EXPAND_AS_DEFINED      = BOOST_AFIO_DEADLINE_NAME BOOST_CXX14_CONSTEXPR  \
     BOOST_AFIO_HEADERS_ONLY_MEMFUNC_SPEC BOOST_AFIO_HEADERS_ONLY_FUNC_SPEC BOOST_AFIO_HEADERS_ONLY_VIRTUAL_SPEC \
     BOOST_AFIO_BITFIELD_BEGIN BOOST_AFIO_BITFIELD_END \
-    BOOST_AFIO_V2_NAMESPACE BOOST_AFIO_V2_NAMESPACE_BEGIN BOOST_AFIO_V2_NAMESPACE_END
+    BOOST_AFIO_V2_NAMESPACE BOOST_AFIO_V2_NAMESPACE_BEGIN BOOST_AFIO_V2_NAMESPACE_EXPORT_BEGIN BOOST_AFIO_V2_NAMESPACE_END \
+    BOOST_AFIO_VERSION_GLUE2 BOOST_AFIO_VERSION_GLUE BOOST_AFIO_HEADERS_PATH4 BOOST_AFIO_HEADERS_PATH3 BOOST_AFIO_HEADERS_PATH2 \
+    BOOST_AFIO_HEADERS_PATH BOOST_AFIO_MODULE_NAME \
+    BOOST_AFIO_VERSION_MAJOR BOOST_AFIO_VERSION_MINOR
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have
diff --git a/Readme.md b/Readme.md
index 04af266c..7f0596d2 100644
--- a/Readme.md
+++ b/Readme.md
@@ -7,6 +7,11 @@ v2 rewrite. You can view its documentation at https://ned14.github.io/boost.afio
 
 CMake todos:
 - Add doxygen generation support
+  - Add ctest script to build the docs (and report warnings to cdash)
+    - cmake --build . --target afio_docs
+  - Add -Wdocumentation when clang is in use. Add -fcomment-block-commands=complexity
+    etc for all our custom doxygen commands.
+  - Get travis to push latest doxygen docs to github for me
 - For non-embedded config, cmake should stamp git submodule SHAs so I can
 dispense with the upd method of submodule stamping
 - Static library edition appears to not be encoding extended error code detail?
diff --git a/include/boost/afio/afio.hpp b/include/boost/afio/afio.hpp
index bbcf10ee..9710db3d 100644
--- a/include/boost/afio/afio.hpp
+++ b/include/boost/afio/afio.hpp
@@ -1,3 +1,4 @@
+//! \file afio/afio.hpp The master *latest version* AFIO include file. All AFIO consuming libraries should include this header only.
 #include "version.hpp"
 
 #if defined(_MSC_VER) && !defined(__clang)
@@ -6,16 +7,12 @@
 #define BOOST_AFIO_HEADERS_PATH2 BOOST_AFIO_VERSION_GLUE(v, BOOST_AFIO_HEADERS_VERSION,)/afio.hpp
 #endif
 
-#undef BOOST_AFIO_MODULE_NAME
-#if defined(__cpp_modules)
-#if defined(_MSC_VER) && !defined(__clang)
-#define BOOST_AFIO_MODULE_NAME BOOST_AFIO_VERSION_GLUE(afio_v, BOOST_AFIO_NAMESPACE_VERSION,)
-#else
-#define BOOST_AFIO_MODULE_NAME BOOST_AFIO_VERSION_GLUE(afio_v, BOOST_AFIO_NAMESPACE_VERSION,)
-#endif
-#endif
-
 #define BOOST_AFIO_HEADERS_PATH4(a) #a
 #define BOOST_AFIO_HEADERS_PATH3(a) BOOST_AFIO_HEADERS_PATH4(a)
+//! \brief The AFIO headers path generated by the preprocessor from the version
 #define BOOST_AFIO_HEADERS_PATH BOOST_AFIO_HEADERS_PATH3(BOOST_AFIO_HEADERS_PATH2)
 #include BOOST_AFIO_HEADERS_PATH
+#undef BOOST_AFIO_HEADERS_PATH
+#undef BOOST_AFIO_HEADERS_PATH2
+#undef BOOST_AFIO_HEADERS_PATH3
+#undef BOOST_AFIO_HEADERS_PATH4
diff --git a/include/boost/afio/v2.0/afio.hpp b/include/boost/afio/v2.0/afio.hpp
index e4610955..6c33fc3c 100644
--- a/include/boost/afio/v2.0/afio.hpp
+++ b/include/boost/afio/v2.0/afio.hpp
@@ -1,3 +1,37 @@
+//! \file v2.0/afio.hpp The master *versioned* AFIO include file. All version specific AFIO consuming libraries should include this header only.
+
+#undef BOOST_AFIO_VERSION_MAJOR
+#undef BOOST_AFIO_VERSION_MINOR
+#undef BOOST_AFIO_VERSION_PATCH
+// Remove any previously defined versioning
+#undef BOOST_AFIO_VERSION_REVISION
+#undef BOOST_AFIO_VERSION_GLUE2
+#undef BOOST_AFIO_VERSION_GLUE
+#undef BOOST_AFIO_HEADERS_VERSION
+#undef BOOST_AFIO_NAMESPACE_VERSION
+#undef BOOST_AFIO_MODULE_NAME
+
+#define BOOST_AFIO_VERSION_GLUE2(a, b, c) a ## b ## c
+#define BOOST_AFIO_VERSION_GLUE(a, b, c)  BOOST_AFIO_VERSION_GLUE2(a, b, c)
+
+// Hard coded as this is a specific version
+#define BOOST_AFIO_VERSION_MAJOR    2
+#define BOOST_AFIO_VERSION_MINOR    0
+#define BOOST_AFIO_VERSION_PATCH    0
+#define BOOST_AFIO_VERSION_REVISION 0
+//! \brief The namespace boost::afio::v ## BOOST_AFIO_NAMESPACE_VERSION
+#define BOOST_AFIO_NAMESPACE_VERSION   BOOST_AFIO_VERSION_GLUE(BOOST_AFIO_VERSION_MAJOR, _, BOOST_AFIO_VERSION_MINOR)
+
+#if defined(__cpp_modules) || defined(DOXYGEN_SHOULD_SKIP_THIS)
+#if defined(_MSC_VER) && !defined(__clang)
+//! \brief The AFIO C++ module name
+#define BOOST_AFIO_MODULE_NAME BOOST_AFIO_VERSION_GLUE(afio_v, BOOST_AFIO_NAMESPACE_VERSION,)
+#else
+//! \brief The AFIO C++ module name
+#define BOOST_AFIO_MODULE_NAME BOOST_AFIO_VERSION_GLUE(afio_v, BOOST_AFIO_NAMESPACE_VERSION,)
+#endif
+#endif
+
 // If C++ Modules are on and we are not compiling the library,
 // we are either generating the interface or importing
 #if defined(__cpp_modules)
@@ -21,6 +55,8 @@ import BOOST_AFIO_MODULE_NAME;
 
 #ifdef BOOST_AFIO_INCLUDE_ALL
 
+#include "config.hpp"
+
 #include "async_file_handle.hpp"
 #include "statfs.hpp"
 #include "storage_profile.hpp"
diff --git a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp
index 9df3b950..d2762a78 100644
--- a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp
+++ b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp
@@ -37,6 +37,8 @@ DEALINGS IN THE SOFTWARE.
 
 #include <cassert>
 
+//! \file atomic_append.hpp Provides algorithm::shared_fs_mutex::atomic_append
+
 BOOST_AFIO_V2_NAMESPACE_BEGIN
 
 namespace algorithm
diff --git a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/base.hpp b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/base.hpp
index 306533ca..3c2b58cc 100644
--- a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/base.hpp
+++ b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/base.hpp
@@ -35,6 +35,8 @@ DEALINGS IN THE SOFTWARE.
 #include "../../handle.hpp"
 #include "../../utils.hpp"
 
+//! \file base.hpp Provides algorithm::shared_fs_mutex::shared_fs_mutex
+
 BOOST_AFIO_V2_NAMESPACE_BEGIN
 
 namespace algorithm
diff --git a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/byte_ranges.hpp b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/byte_ranges.hpp
index 337a5ddf..96ba7e81 100644
--- a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/byte_ranges.hpp
+++ b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/byte_ranges.hpp
@@ -35,6 +35,8 @@ DEALINGS IN THE SOFTWARE.
 #include "../../file_handle.hpp"
 #include "base.hpp"
 
+//! \file byte_ranges.hpp Provides algorithm::shared_fs_mutex::byte_ranges
+
 BOOST_AFIO_V2_NAMESPACE_BEGIN
 
 namespace algorithm
diff --git a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/lock_files.hpp b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/lock_files.hpp
index baa8beb0..9454c903 100644
--- a/include/boost/afio/v2.0/algorithm/shared_fs_mutex/lock_files.hpp
+++ b/include/boost/afio/v2.0/algorithm/shared_fs_mutex/lock_files.hpp
@@ -35,6 +35,8 @@ DEALINGS IN THE SOFTWARE.
 #include "../../file_handle.hpp"
 #include "base.hpp"
 
+//! \file lock_files.hpp Provides algorithm::shared_fs_mutex::lock_files
+
 BOOST_AFIO_V2_NAMESPACE_BEGIN
 
 namespace algorithm
diff --git a/include/boost/afio/v2.0/async_file_handle.hpp b/include/boost/afio/v2.0/async_file_handle.hpp
index 10d39f49..dab82664 100644
--- a/include/boost/afio/v2.0/async_file_handle.hpp
+++ b/include/boost/afio/v2.0/async_file_handle.hpp
@@ -32,6 +32,8 @@ DEALINGS IN THE SOFTWARE.
 #include "file_handle.hpp"
 #include "io_service.hpp"
 
+//! \file async_file_handle.hpp Provides async_file_handle
+
 #ifndef BOOST_AFIO_ASYNC_FILE_HANDLE_H
 #define BOOST_AFIO_ASYNC_FILE_HANDLE_H
 
diff --git a/include/boost/afio/v2.0/config.hpp b/include/boost/afio/v2.0/config.hpp
index 07955c37..7bb0fa1b 100644
--- a/include/boost/afio/v2.0/config.hpp
+++ b/include/boost/afio/v2.0/config.hpp
@@ -29,34 +29,37 @@ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 */
 
-//! \def BOOST_AFIO_HEADERS_ONLY Whether AFIO is a headers only library. Defaults to 1 unless BOOST_ALL_DYN_LINK is defined.
+//! \file config.hpp Configures a compiler environment for AFIO header and source code
+#define BOOST_AFIO_CONFIGURED
+
 #if !defined(BOOST_AFIO_HEADERS_ONLY) && !defined(BOOST_ALL_DYN_LINK)
+//! Whether AFIO is a headers only library. Defaults to 1 unless BOOST_ALL_DYN_LINK is defined.
 #define BOOST_AFIO_HEADERS_ONLY 1
 #endif
 
-//! \def BOOST_AFIO_LOGGING_LEVEL How much detail to log. 0=disabled, 1=fatal, 2=error, 3=warn, 4=info, 5=debug, 6=all.
-//! Defaults to error if NDEBUG defined, else info level.
 #if !defined(BOOST_AFIO_LOGGING_LEVEL)
 #ifdef NDEBUG
 #define BOOST_AFIO_LOGGING_LEVEL 2  // error
 #else
+//! \brief How much detail to log. 0=disabled, 1=fatal, 2=error, 3=warn, 4=info, 5=debug, 6=all.
+//! Defaults to error if NDEBUG defined, else info level.
 #define BOOST_AFIO_LOGGING_LEVEL 4  // info
 #endif
 #endif
 
-//! \def BOOST_AFIO_LOG_BACKTRACE_LEVELS Bit mask of which log levels should be stack backtraced
+#if !defined(BOOST_AFIO_LOG_BACKTRACE_LEVELS)
+//! \brief Bit mask of which log levels should be stack backtraced
 //! which will slow those logs thirty fold or so. Defaults to (1<<1)|(1<<2)|(1<<3) i.e. stack backtrace
 //! on fatal, error and warn logs.
-#if !defined(BOOST_AFIO_LOG_BACKTRACE_LEVELS)
 #define BOOST_AFIO_LOG_BACKTRACE_LEVELS ((1 << 1) | (1 << 2) | (1 << 3))
 #endif
 
-//! \def BOOST_AFIO_LOGGING_MEMORY How much memory to use for the log.
-//! Defaults to 4Kb if NDEBUG defined, else 1Mb.
 #if !defined(BOOST_AFIO_LOGGING_MEMORY)
 #ifdef NDEBUG
 #define BOOST_AFIO_LOGGING_MEMORY 4096
 #else
+//! \brief How much memory to use for the log.
+//! Defaults to 4Kb if NDEBUG defined, else 1Mb.
 #define BOOST_AFIO_LOGGING_MEMORY (1024 * 1024)
 #endif
 #endif
@@ -199,6 +202,14 @@ namespace boost
       namespace algorithm
       {
       }
+      //! YAML databaseable empirical testing of a storage's behaviour
+      namespace storage_profile
+      {
+      }
+      //! Utility routines often useful when using AFIO
+      namespace utils
+      {
+      }
     }
   }
 }
diff --git a/include/boost/afio/v2.0/deadline.h b/include/boost/afio/v2.0/deadline.h
index e33f8b9e..c11ee4ae 100644
--- a/include/boost/afio/v2.0/deadline.h
+++ b/include/boost/afio/v2.0/deadline.h
@@ -35,7 +35,12 @@ DEALINGS IN THE SOFTWARE.
 #include <stdbool.h>
 #include <time.h>
 
+//! \file deadline.h Provides struct deadline
+
 #ifdef __cplusplus
+#ifndef BOOST_AFIO_CONFIGURED
+#error You must include the master afio.hpp, not individual header files directly
+#endif
 #include "config.hpp"
 #include <stdexcept>
 BOOST_AFIO_V2_NAMESPACE_EXPORT_BEGIN
diff --git a/include/boost/afio/v2.0/file_handle.hpp b/include/boost/afio/v2.0/file_handle.hpp
index 831820c5..7aec9360 100644
--- a/include/boost/afio/v2.0/file_handle.hpp
+++ b/include/boost/afio/v2.0/file_handle.hpp
@@ -34,6 +34,8 @@ DEALINGS IN THE SOFTWARE.
 
 #include "handle.hpp"
 
+//! \file file_handle.hpp Provides file_handle
+
 #ifdef _MSC_VER
 #pragma warning(push)
 #pragma warning(disable : 4251)  // dll interface
diff --git a/include/boost/afio/v2.0/handle.hpp b/include/boost/afio/v2.0/handle.hpp
index 63045b10..244c471c 100644
--- a/include/boost/afio/v2.0/handle.hpp
+++ b/include/boost/afio/v2.0/handle.hpp
@@ -38,6 +38,8 @@ DEALINGS IN THE SOFTWARE.
 #include <utility>  // for pair<>
 #include <vector>
 
+//! \file handle.hpp Provides handle
+
 #ifdef _MSC_VER
 #pragma warning(push)
 #pragma warning(disable : 4251)  // dll interface
diff --git a/include/boost/afio/v2.0/io_service.hpp b/include/boost/afio/v2.0/io_service.hpp
index 3e0d6957..c2ea5e66 100644
--- a/include/boost/afio/v2.0/io_service.hpp
+++ b/include/boost/afio/v2.0/io_service.hpp
@@ -39,19 +39,17 @@ DEALINGS IN THE SOFTWARE.
 
 #undef _threadid  // windows macro splosh sigh
 
-//!\def BOOST_AFIO_COMPILE_KQUEUES Undefined to autodetect, 1 to compile in BSD kqueue support, 0 to leave it out
-/*!\def BOOST_AFIO_USE_POSIX_AIO Undefined to autodetect, 1 to use POSIX AIO, 0 to not use
-
-\warning On FreeBSD the AIO kernel module needs to be loaded for POSIX AIO to work.
-Run as root 'kldload aio' or add 'aio_load=YES' in loader.conf.
-*/
-//!\def BOOST_AFIO_IO_POST_SIGNAL Undefined to autoset to first free SIGRTMIN if realtime signals available, else SIGUSR1. Only used if BOOST_AFIO_USE_KQUEUES=0.
-//!\def BOOST_AFIO_HAVE_REALTIME_SIGNALS Undefined to autodetect. 0 to use non-realtime signals. Note performance in this use case is abysmal.
+//! \file io_service.hpp Provides io_service
 
 // Need to decide which kind of POSIX AIO to use
 #ifndef _WIN32
 // Right now the only thing we support is POSIX AIO
 #if !defined(BOOST_AFIO_USE_POSIX_AIO)
+/*! \brief Undefined to autodetect, 1 to use POSIX AIO, 0 to not use
+
+\warning On FreeBSD the AIO kernel module needs to be loaded for POSIX AIO to work.
+Run as root 'kldload aio' or add 'aio_load=YES' in loader.conf.
+*/
 #define BOOST_AFIO_USE_POSIX_AIO 1
 #endif
 // BSD kqueues not implemented yet
@@ -66,6 +64,10 @@ Run as root 'kldload aio' or add 'aio_load=YES' in loader.conf.
 #define BOOST_AFIO_USE_POSIX_AIO 1
 #endif
 #endif
+#if DOXYGEN_SHOULD_SKIP_THIS
+//! Undefined to autodetect, 1 to compile in BSD kqueue support, 0 to leave it out
+#define BOOST_AFIO_COMPILE_KQUEUES <see docs>
+#endif
 
 #if BOOST_AFIO_USE_POSIX_AIO
 // We'll be using POSIX AIO and signal based interruption for post()
@@ -78,8 +80,10 @@ Run as root 'kldload aio' or add 'aio_load=YES' in loader.conf.
 #define BOOST_AFIO_HAVE_REALTIME_SIGNALS 1
 #else
 #ifndef BOOST_AFIO_IO_POST_SIGNAL
+//! Undefined to autoset to first free SIGRTMIN if realtime signals available, else SIGUSR1. Only used if BOOST_AFIO_USE_KQUEUES=0.
 #define BOOST_AFIO_IO_POST_SIGNAL (SIGUSR1)
 #endif
+//! Undefined to autodetect. 0 to use non-realtime signals. Note performance in this use case is abysmal.
 #define BOOST_AFIO_HAVE_REALTIME_SIGNALS 0
 #endif
 struct aiocb;
diff --git a/include/boost/afio/v2.0/native_handle_type.hpp b/include/boost/afio/v2.0/native_handle_type.hpp
index 71c8608e..4b2c0203 100644
--- a/include/boost/afio/v2.0/native_handle_type.hpp
+++ b/include/boost/afio/v2.0/native_handle_type.hpp
@@ -29,8 +29,13 @@ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 */
 
+#ifndef BOOST_AFIO_CONFIGURED
+#error You must include the master afio.hpp, not individual header files directly
+#endif
 #include "config.hpp"
 
+//! \file native_handle_type.hpp Provides native_handle_type
+
 #ifndef BOOST_AFIO_NATIVE_HANDLE_TYPE_H
 #define BOOST_AFIO_NATIVE_HANDLE_TYPE_H
 
diff --git a/include/boost/afio/v2.0/statfs.hpp b/include/boost/afio/v2.0/statfs.hpp
index 11d85367..1ed90232 100644
--- a/include/boost/afio/v2.0/statfs.hpp
+++ b/include/boost/afio/v2.0/statfs.hpp
@@ -32,8 +32,13 @@ DEALINGS IN THE SOFTWARE.
 #ifndef BOOST_AFIO_STATFS_H
 #define BOOST_AFIO_STATFS_H
 
+#ifndef BOOST_AFIO_CONFIGURED
+#error You must include the master afio.hpp, not individual header files directly
+#endif
 #include "config.hpp"
 
+//! \file statfs.hpp Provides statfs
+
 #ifdef _MSC_VER
 #pragma warning(push)
 #pragma warning(disable : 4251)  // dll interface
diff --git a/include/boost/afio/v2.0/storage_profile.hpp b/include/boost/afio/v2.0/storage_profile.hpp
index ac49112e..07329149 100644
--- a/include/boost/afio/v2.0/storage_profile.hpp
+++ b/include/boost/afio/v2.0/storage_profile.hpp
@@ -34,6 +34,8 @@ DEALINGS IN THE SOFTWARE.
 
 #include <regex>
 
+//! \file storage_profile.hpp Provides storage_profile
+
 #ifdef _MSC_VER
 #pragma warning(push)
 #pragma warning(disable : 4251)  // dll interface
diff --git a/include/boost/afio/v2.0/utils.hpp b/include/boost/afio/v2.0/utils.hpp
index 9712c18a..8679d6bc 100644
--- a/include/boost/afio/v2.0/utils.hpp
+++ b/include/boost/afio/v2.0/utils.hpp
@@ -32,11 +32,15 @@ DEALINGS IN THE SOFTWARE.
 #ifndef BOOST_AFIO_UTILS_H
 #define BOOST_AFIO_UTILS_H
 
+#ifndef BOOST_AFIO_CONFIGURED
+#error You must include the master afio.hpp, not individual header files directly
+#endif
 #include "config.hpp"
 
+//! \file utils.hpp Provides namespace utils
+
 BOOST_AFIO_V2_NAMESPACE_EXPORT_BEGIN
 
-//! Utility routines often useful when using AFIO
 namespace utils
 {
   /*! \brief Returns the page sizes of this architecture which is useful for calculating direct i/o multiples.
diff --git a/index.html b/index.html
new file mode 100644
index 00000000..32c29efe
--- /dev/null
+++ b/index.html
@@ -0,0 +1,4 @@
+<html>
+<head><meta http-equiv="refresh" content="0; url=doc/html/index.html" /></head>
+<body>Please go to <a href="doc/index.html">doc/html/index.html</a></body>
+</html>