doxygen fixes, reenabled Appveyor but with clang/LLVM

11 files changed, 40 insertions, 25 deletions

diff --git a/Doxyfile b/Doxyfile
index b8e9a4b5..9039dda7 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2032,7 +2032,7 @@ PREDEFINED             = DOXYGEN_IS_IN_THE_HOUSE=1 DOXYGEN_SHOULD_SKIP_THIS=1 \
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      = AFIO_DEADLINE_NAME QUICKCPPLIB_CONSTEXPR  \
+EXPAND_AS_DEFINED      = AFIO_DECL AFIO_DEADLINE_NAME QUICKCPPLIB_CONSTEXPR  \
     AFIO_HEADERS_ONLY_MEMFUNC_SPEC AFIO_HEADERS_ONLY_FUNC_SPEC AFIO_HEADERS_ONLY_VIRTUAL_SPEC \
     QUICKCPPLIB_BITFIELD_BEGIN QUICKCPPLIB_BITFIELD_END \
     AFIO_V2_NAMESPACE AFIO_V2_NAMESPACE_BEGIN AFIO_V2_NAMESPACE_EXPORT_BEGIN AFIO_V2_NAMESPACE_END \
diff --git a/appveyor.yml.disabled b/appveyor.yml
index 44715d21..11401c26 100644
--- a/appveyor.yml.disabled
+++ b/appveyor.yml
@@ -24,7 +24,7 @@ before_build:
   - git checkout master
   - git submodule update --init --recursive
 build_script:
-  - ctest -S .ci.cmake -V --timeout 300
+  - ctest -S .ci.cmake -V --timeout 300 --build-generator-toolset LLVM-vs2014
 after_build:
 
 before_test:
diff --git a/include/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp b/include/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp
index a7182556..b99e2c5e 100644
--- a/include/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp
+++ b/include/afio/v2.0/algorithm/shared_fs_mutex/atomic_append.hpp
@@ -165,6 +165,7 @@ namespace algorithm
       /*! Initialises a shared filing system mutex using the file at \em lockfile
 
       \return An implementation of shared_fs_mutex using the atomic_append algorithm.
+      \param base Optional base for the path to the file.
       \param lockfile The path to the file to use for IPC.
       \param nfs_compatibility Make this true if the lockfile could be accessed by NFS.
       \param skip_hashing Some filing systems (typically the copy on write ones e.g.
diff --git a/include/afio/v2.0/async_file_handle.hpp b/include/afio/v2.0/async_file_handle.hpp
index da2005a3..66dc95e5 100644
--- a/include/afio/v2.0/async_file_handle.hpp
+++ b/include/afio/v2.0/async_file_handle.hpp
@@ -32,7 +32,9 @@ Distributed under the Boost Software License, Version 1.0.
 
 AFIO_V2_NAMESPACE_EXPORT_BEGIN
 
-/*! An asynchronous handle to an open something
+/*! \class async_file_handle
+\brief An asynchronous handle to an open something
+
 \todo Direct use of `calloc()` ought to be replaced with a user supplied STL allocator instance.
 */
 class AFIO_DECL async_file_handle : public file_handle
diff --git a/include/afio/v2.0/config.hpp b/include/afio/v2.0/config.hpp
index 205e7b29..7b049b1a 100644
--- a/include/afio/v2.0/config.hpp
+++ b/include/afio/v2.0/config.hpp
@@ -139,7 +139,7 @@ Distributed under the Boost Software License, Version 1.0.
 \brief The namespace configuration of this AFIO v2. Consists of a sequence
 of bracketed tokens later fused by the preprocessor into namespace and C++ module names.
 */
-#if DOXYGEN_SHOULD_SKIP_THIS
+#if DOXYGEN_IS_IN_THE_HOUSE
 //! The AFIO namespace
 namespace afio_v2_xxx
 {
@@ -166,14 +166,14 @@ namespace starting with `v2_` inside the `boost::afio` namespace.
 */
 #define AFIO_V2_NAMESPACE_BEGIN                                                                                                                                                                                                                                                                                                \
   namespace afio_v2_xxx                                                                                                                                                                                                                                                                                                        \
-  {  \
+  {
 /*! \brief Expands into the appropriate namespace markup to enter the C++ module
 exported AFIO v2 namespace.
 \ingroup config
 */
 #define AFIO_V2_NAMESPACE_EXPORT_BEGIN                                                                                                                                                                                                                                                                                         \
   export namespace afio_v2_xxx                                                                                                                                                                                                                                                                                                 \
-  {  \
+  {
 /*! \brief Expands into the appropriate namespace markup to exit the AFIO v2 namespace.
 \ingroup config
 */
@@ -229,7 +229,7 @@ AFIO_V2_NAMESPACE_END
 #define AFIO_DECL QUICKCPPLIB_SYMBOL_EXPORT
 #define AFIO_BUILD_DLL
 #else
-#define AFIO_DECL BOOSTLIE_SYMBOL_IMPORT
+#define AFIO_DECL QUICKCPPLIB_SYMBOL_IMPORT
 #endif
 #else
 #define AFIO_DECL
@@ -281,6 +281,9 @@ AFIO_V2_NAMESPACE_END
 #include "../outcome/include/outcome.hpp"
 AFIO_V2_NAMESPACE_BEGIN
 // Specialise error_code into this namespace so we can hook result creation via ADL
+/*! \struct error_code
+\brief Trampoline to `std::error_code`, used to ADL hook `result<T, E>` creation in Outcome.
+*/
 struct error_code : public std::error_code
 {
   // literally passthrough
diff --git a/include/afio/v2.0/deadline.h b/include/afio/v2.0/deadline.h
index 62f17ba4..56cd33f1 100644
--- a/include/afio/v2.0/deadline.h
+++ b/include/afio/v2.0/deadline.h
@@ -30,7 +30,7 @@ Distributed under the Boost Software License, Version 1.0.
 
 //! \file deadline.h Provides struct deadline
 
-#ifdef __cplusplus
+#if defined(__cplusplus) || DOXYGEN_IS_IN_THE_HOUSE
 #ifndef AFIO_CONFIG_HPP
 #error You must include the master afio.hpp, not individual header files directly
 #endif
@@ -90,7 +90,7 @@ struct AFIO_DEADLINE_NAME
 };
 
 #undef AFIO_DEADLINE_NAME
-#ifdef __cplusplus
+#if defined(__cplusplus) || DOXYGEN_IS_IN_THE_HOUSE
 AFIO_V2_NAMESPACE_END
 #endif
 
diff --git a/include/afio/v2.0/file_handle.hpp b/include/afio/v2.0/file_handle.hpp
index a2fa9061..18875c5f 100644
--- a/include/afio/v2.0/file_handle.hpp
+++ b/include/afio/v2.0/file_handle.hpp
@@ -57,7 +57,6 @@ class io_service;
 /*! \class file_handle
 \brief A handle to a regular file or device, kept data layout compatible with
 async_file_handle.
-\todo file_handle needs to be split into a pathed_handle for the file and directory common parts
 */
 class AFIO_DECL file_handle : public io_handle
 {
diff --git a/include/afio/v2.0/handle.hpp b/include/afio/v2.0/handle.hpp
index c4a9d321..e7caaf35 100644
--- a/include/afio/v2.0/handle.hpp
+++ b/include/afio/v2.0/handle.hpp
@@ -143,7 +143,8 @@ public:
     overlapped = 1 << 28,         //!< On Windows, create any new handles with OVERLAPPED semantics
     byte_lock_insanity = 1 << 29  //!< Using insane POSIX byte range locks
   }
-  QUICKCPPLIB_BITFIELD_END(flag)
+  QUICKCPPLIB_BITFIELD_END(flag);
+
 protected:
   caching _caching;
   flag _flags;
diff --git a/include/afio/v2.0/io_handle.hpp b/include/afio/v2.0/io_handle.hpp
index 776a7103..da9d372c 100644
--- a/include/afio/v2.0/io_handle.hpp
+++ b/include/afio/v2.0/io_handle.hpp
@@ -50,7 +50,7 @@ public:
   using caching = handle::caching;
   using flag = handle::flag;
 
-  //! The scatter buffer type used by this handle
+  //! The scatter buffer type used by this handle. Guaranteed to be `TrivialType` and `StandardLayoutType`.
   struct buffer_type
   {
     //! Pointer to memory to be filled by a read. Try to make this 64 byte, or ideally, `page_size()` aligned where possible.
@@ -58,7 +58,7 @@ public:
     //! The number of bytes to fill into this address. Try to make this a 64 byte multiple, or ideally, a whole multiple of `page_size()`.
     size_t len;
   };
-  //! The gather buffer type used by this handle
+  //! The gather buffer type used by this handle. Guaranteed to be `TrivialType` and `StandardLayoutType`.
   struct const_buffer_type
   {
     //! Pointer to memory to be written. Try to make this 64 byte, or ideally, `page_size()` aligned where possible.
@@ -72,9 +72,9 @@ public:
   static_assert(std::is_standard_layout<buffer_type>::value, "buffer_type is not a standard layout type!");
   static_assert(std::is_standard_layout<const_buffer_type>::value, "const_buffer_type is not a standard layout type!");
 #endif
-  //! The scatter buffers type used by this handle
+  //! The scatter buffers type used by this handle. Guaranteed to be `TrivialType` apart from construction, and `StandardLayoutType`.
   using buffers_type = span<buffer_type>;
-  //! The gather buffers type used by this handle
+  //! The gather buffers type used by this handle. Guaranteed to be `TrivialType` apart from construction, and `StandardLayoutType`.
   using const_buffers_type = span<const_buffer_type>;
 #ifndef NDEBUG
   // Is trivial in all ways, except default constructibility
@@ -87,7 +87,7 @@ public:
   static_assert(std::is_trivially_move_assignable<buffers_type>::value, "buffers_type is not trivially move assignable!");
   static_assert(std::is_standard_layout<buffers_type>::value, "buffers_type is not a standard layout type!");
 #endif
-  //! The i/o request type used by this handle
+  //! The i/o request type used by this handle. Guaranteed to be `TrivialType` apart from construction, and `StandardLayoutType`.
   template <class T> struct io_request
   {
     T buffers;
@@ -114,7 +114,7 @@ public:
   static_assert(std::is_trivially_move_assignable<io_request<buffers_type>>::value, "io_request<buffers_type> is not trivially move assignable!");
   static_assert(std::is_standard_layout<io_request<buffers_type>>::value, "io_request<buffers_type> is not a standard layout type!");
 #endif
-  //! The i/o result type used by this handle
+  //! The i/o result type used by this handle. Guaranteed to be `TrivialType` apart from construction, and `StandardLayoutType`.
   template <class T> class io_result : public result<T>
   {
     using Base = result<T>;
diff --git a/include/afio/v2.0/map_handle.hpp b/include/afio/v2.0/map_handle.hpp
index 8d18ea2b..1939888a 100644
--- a/include/afio/v2.0/map_handle.hpp
+++ b/include/afio/v2.0/map_handle.hpp
@@ -62,7 +62,7 @@ public:
                                    // NOTE: IF UPDATING THIS UPDATE THE std::ostream PRINTER BELOW!!!
 
                                    readwrite = (read | write)};
-  QUICKCPPLIB_BITFIELD_END(flag)
+  QUICKCPPLIB_BITFIELD_END(flag);
 
 protected:
   io_handle *_backing;
diff --git a/release_notes.md b/release_notes.md
index 851d6081..b2efa43d 100644
--- a/release_notes.md
+++ b/release_notes.md
@@ -1,15 +1,24 @@
-Herein lies the beginnings of the proposed AFIO v2 post-peer-review rewrite. Its github
-source code repository lives at https://github.com/ned14/boost.afio.
+<center><table border="0" cellpadding="4">
+<tr>
+<td align="center"> <a href="https://github.com/ned14/afio">AFIO</a><br><a href="https://github.com/ned14/afio">on GitHub</a> </td>
+<td align="center"> <a href="http://my.cdash.org/index.php?project=Boost.AFIO">CTest summary</a><br><a href="http://my.cdash.org/index.php?project=Boost.AFIO">dashboard</a> </td>
+<td align="center"> <a href="https://travis-ci.org/ned14/boost.outcome">Linux and MacOS CI:</a><img src="https://travis-ci.org/ned14/afio.svg?branch=master"/> </td>
+<td align="center"> <a href="https://ci.appveyor.com/project/ned14/afio/branch/master">Windows CI:</a><img src="https://ci.appveyor.com/api/projects/status/680b1pt9srnoprs3/branch/master?svg=true"/> </td>
+</tr>
+</table></center>
 
-<b>master branch test status</b> Linux: <a href="https://travis-ci.org/ned14/afio"><img src="https://travis-ci.org/ned14/afio.svg?branch=master"></a> Windows: <em>disabled due to lack of VS2017.3 on CI</em> <b>CMake dashboard</b>: http://my.cdash.org/index.php?project=AFIO
+Herein lies my proposed async file i/o and filesystem library for Boost and the C++ standard.
+It is a complete rewrite after a Boost peer review in August 2015. Its github
+source code repository lives at https://github.com/ned14/boost.afio.
 
-\note Note that this code is of late alpha quality. Be careful when using it!
+\note Note that this code is of late alpha quality. It's quite reliable, but be careful when using it!
 
 You need these compilers or better:
-- GCC 7.0
-- clang 4.0
-- VS2017 Update 3
+- GCC 7.0 (Linux)
+- clang 4.0 (Linux, Windows)
+- VS2017 Update 3 (Windows)
 
+Todo list for already implemented parts: https://ned14.github.io/afio/todo.html
 
 ## v2 architecture and design implemented: