doxygen: Substantially improve the rendition of the doxygen docs by fixes and adding lots more hackery and workarounds.

12 files changed, 75 insertions, 24 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 604416c6..b256c7d7 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -119,7 +119,7 @@ endif()
 if(NOT PROJECT_IS_DEPENDENCY)
   if(NOT PYTHONINTERP_FOUND)
     indented_message(WARNING "NOT rebuilding preprocessed edition of library due to python not being installed")
-  elseif(FALSE)
+  else()
     function(make_single_header target name)
       add_partial_preprocess(${target}
                             "${name}"
@@ -155,6 +155,30 @@ if(NOT PROJECT_IS_DEPENDENCY)
                        -D QUICKCPPLIB_DISABLE_ABI_PERMUTATION=1
                        -U LLFIO_UNSTABLE_VERSION
                        -U OUTCOME_UNSTABLE_VERSION)
+#    add_partial_preprocess(llfio_hl-docs
+#                          "${CMAKE_CURRENT_SOURCE_DIR}/single-header/docs.hpp"
+#                          "${CMAKE_CURRENT_SOURCE_DIR}/include/llfio/revision.hpp"
+#                          "${CMAKE_CURRENT_SOURCE_DIR}/include/llfio/v2.0/llfio.hpp"
+#                          -D QUICKCPPLIB_USE_STD_BYTE -D QUICKCPPLIB_USE_STD_OPTIONAL -D QUICKCPPLIB_USE_STD_SPAN
+#                          -U gsl_COMPILER_MSVC_VERSION -U gsl_HAS_CPP0X -D gsl_CPLUSPLUS=201703 -D __cplusplus=201703
+#                          -D LLFIO_HEADERS_ONLY=0
+#                          -D LLFIO_DISABLE_ABI_PERMUTATION=1
+#                          -D OUTCOME_DISABLE_ABI_PERMUTATION=1
+#                          -D QUICKCPPLIB_DISABLE_ABI_PERMUTATION=1
+#                          -U LLFIO_UNSTABLE_VERSION
+#                          -U OUTCOME_UNSTABLE_VERSION
+#                          -I ../quickcpplib/include -I ../outcome/include
+#                          --passthru-unfound-includes
+#                          --passthru-comments # --debug
+#                          -U QUICKCPPLIB_ENABLE_VALGRIND
+#                          -D DOXYGEN_SHOULD_SKIP_THIS -D DOXYGEN_IS_IN_THE_HOUSE
+#                          -U __cpp_modules
+#                          -D LLFIO_INCLUDE_ALL
+#                          WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
+#                          )
+#    if(NOT CMAKE_VERSION VERSION_LESS 3.3)
+#      add_dependencies(llfio_hl llfio_hl-docs)
+#    endif()
   endif()
 
   # Create a custom doxygen generation target
diff --git a/Doxyfile b/Doxyfile
index 65a23522..4308d118 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -229,7 +229,7 @@ TAB_SIZE               = 2
 # newlines.
 
 ALIASES                = "errors=@par Errors returnable\n" "mallocs=@par Memory Allocations\n" \
-			"raceguarantees{1}=@par Race Guarantees\n\1" \
+			"raceguarantees=@par Race Guarantees\n" \
 			"complexity{1}=@par Complexity\n\1" \
       "exceptionmodel{1}=@par Errors returnable\n\1"
 
@@ -2024,7 +2024,16 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DOXYGEN_IS_IN_THE_HOUSE=1 DOXYGEN_SHOULD_SKIP_THIS=1 LLFIO_REQUIRES(...)=
+PREDEFINED             = DOXYGEN_IS_IN_THE_HOUSE=1 DOXYGEN_SHOULD_SKIP_THIS=1 LLFIO_REQUIRES(...)= \
+    QUICKCPPLIB_TEMPLATE(...)="template <__VA_ARGS__" \
+    QUICKCPPLIB_TREQUIRES(...)=", __VA_ARGS__ >" \
+    QUICKCPPLIB_TEXPR(...)="typename = decltype(__VA_ARGS__)" \
+    QUICKCPPLIB_TPRED(...)="typename std::enable_if<(__VA_ARGS__), bool>::type = true" \
+    QUICKCPPLIB_REQUIRES(...)= \
+    QUICKCPPLIB_NODISCARD="[[nodiscard]]" \
+    QUICKCPPLIB_BITFIELD_BEGIN(type)="enum bitfield__##type : unsigned" \
+    QUICKCPPLIB_BITFIELD_BEGIN_T(type, UT)="enum bitfield__##type : UT" \
+    QUICKCPPLIB_BITFIELD_END(type)=";"
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
@@ -2040,7 +2049,10 @@ EXPAND_AS_DEFINED      = LLFIO_DECL LLFIO_DEADLINE_NAME LLFIO_MAKE_FREE_FUNCTION
     LLFIO_VERSION_GLUE2 LLFIO_VERSION_GLUE LLFIO_HEADERS_PATH4 LLFIO_HEADERS_PATH3 LLFIO_HEADERS_PATH2 \
     LLFIO_HEADERS_PATH LLFIO_MODULE_NAME \
     LLFIO_VERSION_MAJOR LLFIO_VERSION_MINOR \
-    LLFIO_REQUIRES LLFIO_DEADLINE_TRY_FOR_UNTIL
+    LLFIO_REQUIRES LLFIO_DEADLINE_TRY_FOR_UNTIL \
+    LLFIO_NODISCARD QUICKCPPLIB_NODISCARD LLFIO_PATH_VIEW_CONSTEXPR \
+    LLFIO_TEMPLATE QUICKCPPLIB_TEMPLATE LLFIO_TREQUIRES QUICKCPPLIB_TREQUIRES LLFIO_TEXPR QUICKCPPLIB_TEXPR LLFIO_TPRED QUICKCPPLIB_TPRED \
+    QUICKCPPLIB_REQUIRES QUICKCPPLIB_BITFIELD_BEGIN QUICKCPPLIB_BITFIELD_BEGIN_T QUICKCPPLIB_BITFIELD_END
 
 EXPAND_AS_DEFINED     += KVSTORE_V1_NAMESPACE KVSTORE_V1_NAMESPACE_BEGIN KVSTORE_V1_NAMESPACE_EXPORT_BEGIN KVSTORE_V1_NAMESPACE_END
 
diff --git a/include/llfio/revision.hpp b/include/llfio/revision.hpp
index 8fa209df..60775912 100644
--- a/include/llfio/revision.hpp
+++ b/include/llfio/revision.hpp
@@ -1,4 +1,4 @@
 // Note the second line of this file must ALWAYS be the git SHA, third line ALWAYS the git SHA update time
-#define LLFIO_PREVIOUS_COMMIT_REF    7986b92283e2d92991fbbc77850faf6025932dc4
-#define LLFIO_PREVIOUS_COMMIT_DATE   "2022-09-01 16:30:55 +00:00"
-#define LLFIO_PREVIOUS_COMMIT_UNIQUE 7986b922
+#define LLFIO_PREVIOUS_COMMIT_REF    fa0940ef959827831f6bbb5ddc7c53c04514d8a6
+#define LLFIO_PREVIOUS_COMMIT_DATE   "2022-09-05 16:26:47 +00:00"
+#define LLFIO_PREVIOUS_COMMIT_UNIQUE fa0940ef
diff --git a/include/llfio/v2.0/algorithm/difference.hpp b/include/llfio/v2.0/algorithm/difference.hpp
index 81de992e..77b0b289 100644
--- a/include/llfio/v2.0/algorithm/difference.hpp
+++ b/include/llfio/v2.0/algorithm/difference.hpp
@@ -27,7 +27,7 @@ Distributed under the Boost Software License, Version 1.0.
 
 #include "traverse.hpp"
 
-//! \file compare.hpp Provides a directory tree difference algorithm.
+//! \file difference.hpp Provides a directory tree difference algorithm.
 
 LLFIO_V2_NAMESPACE_BEGIN
 
diff --git a/include/llfio/v2.0/algorithm/traverse.hpp b/include/llfio/v2.0/algorithm/traverse.hpp
index 274feb81..f8e746f3 100644
--- a/include/llfio/v2.0/algorithm/traverse.hpp
+++ b/include/llfio/v2.0/algorithm/traverse.hpp
@@ -101,7 +101,7 @@ namespace algorithm
     This can act as an estimated progress indicator, or to give an
     accurate progress indicator by matching it against a previous
     traversal.
-    \data The third party data pointer passed to `traverse()`.
+    \param data The third party data pointer passed to `traverse()`.
     \param dirs_processed The total number of directories traversed so far.
     \param known_dirs_remaining The currently known number of directories
     awaiting traversal.
diff --git a/include/llfio/v2.0/config.hpp b/include/llfio/v2.0/config.hpp
index 834a4373..b092952d 100644
--- a/include/llfio/v2.0/config.hpp
+++ b/include/llfio/v2.0/config.hpp
@@ -108,6 +108,7 @@ Distributed under the Boost Software License, Version 1.0.
 
 #include "quickcpplib/cpp_feature.h"
 
+#ifndef STANDARDESE_IS_IN_THE_HOUSE
 #ifndef __cpp_exceptions
 #error LLFIO needs C++ exceptions to be turned on
 #endif
@@ -139,6 +140,7 @@ Distributed under the Boost Software License, Version 1.0.
 #error LLFIO needs an implementation of the Filesystem TS in the standard library
 #endif
 #endif
+#endif
 
 
 #include "quickcpplib/import.h"
@@ -247,10 +249,10 @@ namespace filesystem = std::filesystem;
 LLFIO_V2_NAMESPACE_END
 #endif
 #elif __PCPP_ALWAYS_TRUE__
-#define LLFIO_USING_EXPERIMENTAL_FILESYSTEM 1
-#include <experimental/filesystem>
+#define LLFIO_USING_STD_FILESYSTEM 1
+#include <filesystem>
 LLFIO_V2_NAMESPACE_BEGIN
-namespace filesystem = std::experimental::filesystem;
+namespace filesystem = std::filesystem;
 LLFIO_V2_NAMESPACE_END
 // clang-format on
 #elif defined(_MSC_VER)
diff --git a/include/llfio/v2.0/directory_handle.hpp b/include/llfio/v2.0/directory_handle.hpp
index f70d3106..2867c373 100644
--- a/include/llfio/v2.0/directory_handle.hpp
+++ b/include/llfio/v2.0/directory_handle.hpp
@@ -346,6 +346,8 @@ public:
   was read or not. You should *always* examine `.metadata()` for the metadata you are about to use,
   fetching it with `stat_t::fill()` if not yet present.
   \param req A buffer fill (directory enumeration) request.
+  \param d An optional deadline by which the i/o must complete, else it is cancelled.
+  Note function may return significantly after this deadline if the i/o takes long to cancel.
   \errors todo
   \mallocs If the `kernelbuffer` parameter is set in the request, no memory allocations.
   If unset, at least one memory allocation, possibly more is performed. MAKE SURE you reuse the
diff --git a/include/llfio/v2.0/dynamic_thread_pool_group.hpp b/include/llfio/v2.0/dynamic_thread_pool_group.hpp
index 0db7caa0..0427e64a 100644
--- a/include/llfio/v2.0/dynamic_thread_pool_group.hpp
+++ b/include/llfio/v2.0/dynamic_thread_pool_group.hpp
@@ -35,6 +35,8 @@ Distributed under the Boost Software License, Version 1.0.
 #pragma warning(disable : 4275)  // dll interface
 #endif
 
+//! \file dynamic_thread_pool_group.hpp Provides a dynamic thread pool.
+
 LLFIO_V2_NAMESPACE_EXPORT_BEGIN
 
 class dynamic_thread_pool_group_impl;
diff --git a/include/llfio/v2.0/fs_handle.hpp b/include/llfio/v2.0/fs_handle.hpp
index d8e0c091..3a603429 100644
--- a/include/llfio/v2.0/fs_handle.hpp
+++ b/include/llfio/v2.0/fs_handle.hpp
@@ -139,8 +139,9 @@ inline result<filesystem::path> to_win32_path(const T &h, win32_path_namespace m
 inline result<filesystem::path> to_win32_path(const fs_handle &h, win32_path_namespace mapping = win32_path_namespace::any) noexcept;
 LLFIO_TEMPLATE(class T)
 LLFIO_TREQUIRES(LLFIO_TPRED(!std::is_base_of<fs_handle, T>::value && std::is_base_of<handle, T>::value))
-inline result<filesystem::path> to_win32_path(const T &h, win32_path_namespace /*unused*/ = win32_path_namespace::any) noexcept
+inline result<filesystem::path> to_win32_path(const T &h, win32_path_namespace mapping = win32_path_namespace::any) noexcept
 {
+  (void) mapping;
   return h.current_path();
 }
 #endif
@@ -155,7 +156,11 @@ class LLFIO_DECL fs_handle
 #ifdef _WIN32
   friend LLFIO_HEADERS_ONLY_FUNC_SPEC result<filesystem::path> to_win32_path(const fs_handle &h, win32_path_namespace mapping) noexcept;
 #else
-  friend inline result<filesystem::path> to_win32_path(const fs_handle &h, win32_path_namespace /*unused*/) noexcept { return h._get_handle().current_path(); }
+  friend inline result<filesystem::path> to_win32_path(const fs_handle &h, win32_path_namespace mapping) noexcept
+  {
+    (void) mapping;
+    return h._get_handle().current_path();
+  }
 #endif
 
 public:
diff --git a/include/llfio/v2.0/mapped_file_handle.hpp b/include/llfio/v2.0/mapped_file_handle.hpp
index e3adbe89..5f4f2997 100644
--- a/include/llfio/v2.0/mapped_file_handle.hpp
+++ b/include/llfio/v2.0/mapped_file_handle.hpp
@@ -376,6 +376,7 @@ public:
   \param _caching How to ask the kernel to cache the file.
   \param flags Any additional custom behaviours.
   \param sflags Any additional custom behaviours for the internal `section_handle`.
+  \param offset The offset into the backing file for the map.
 
   Note that if the file is currently zero sized, no mapping occurs now, but
   later when `truncate()` or `update_map()` is called.
diff --git a/release_notes.md b/release_notes.md
index a01c6cd1..e969be61 100644
--- a/release_notes.md
+++ b/release_notes.md
@@ -47,7 +47,7 @@ Examples of use:
 \snippet use_cases.cpp sparse_array
 </td>
 <td width="50%" valign="top">
-\snippet use_cases.cpp coroutine_write
+\snippet tls_socket_handle.cpp https_get
 </td>
 </tr>
 </table>
diff --git a/test/tests/tls_socket_handle.cpp b/test/tests/tls_socket_handle.cpp
index 8e4e3a76..5df7dd3d 100644
--- a/test/tests/tls_socket_handle.cpp
+++ b/test/tests/tls_socket_handle.cpp
@@ -282,12 +282,13 @@ TLS certificate.
 */
 static inline void TestAuthenticatingTLSSocketHandles()
 {
-  static constexpr const char *test_host = "github.com";
-  static constexpr const char *get_request = R"(GET / HTTP/1.0
+  //! [https_get]
+  namespace llfio = LLFIO_V2_NAMESPACE;
+  static constexpr llfio::string_view test_host("github.com");
+  static constexpr llfio::string_view get_request(R"(GET / HTTP/1.0
 Host: github.com
 
-)";
-  namespace llfio = LLFIO_V2_NAMESPACE;
+)");
   if(llfio::tls_socket_source_registry::empty())
   {
     std::cout << "\nNOTE: This platform has no TLS socket sources in its registry, skipping this test." << std::endl;
@@ -313,12 +314,13 @@ Host: github.com
   }
   // Get the front page
   std::cout << "\nThe socket which connected to " << test_host << " negotiated the cipher " << sock->algorithms_description() << std::endl;
-  auto written = sock->write({{(const llfio::byte *) get_request, strlen(get_request)}}).value();
-  BOOST_REQUIRE(written == strlen(get_request));
+  llfio::tls_socket_handle::const_buffer_type get_request_buffer(reinterpret_cast<const llfio::byte *>(get_request.data()), get_request.size());
+  auto written = sock->write({get_request_buffer}).value();
+  BOOST_REQUIRE(written == get_request.size());
   // Fetch the front page. The connection will close once all data is sent.
-  std::vector<char> buffer(4096);
+  std::vector<llfio::byte> buffer(4096);
   size_t offset = 0;
-  for(size_t readed = 0; (readed = sock->read({{(llfio::byte *) buffer.data() + offset, buffer.size() - offset}}, std::chrono::seconds(3)).value()) > 0;)
+  for(size_t readed = 0; (readed = sock->read({{buffer.data() + offset, buffer.size() - offset}}, std::chrono::seconds(3)).value()) > 0;)
   {
     offset += readed;
     if(buffer.size() - offset < 1024)
@@ -328,10 +330,11 @@ Host: github.com
   }
   buffer.resize(offset);
   std::cout << "\nRead from " << test_host << " " << offset << " bytes. The first 1024 bytes are:\n\n"
-            << llfio::string_view(buffer.data(), offset).substr(0, 1024) << "\n"
+            << llfio::string_view(reinterpret_cast<const char *>(buffer.data()), offset).substr(0, 1024) << "\n"
             << std::endl;
   // Make sure this doesn't hang because the socket is closed
   sock->shutdown_and_close().value();
+  //! [https_get]
 }
 
 #if 0