CXX-3085 Upgrade to Doxygen 1.11.0 (#1185)

* doxygen: upgrade to 1.11.0

* doxygen: set MARKDOWN_ID_STYLE = GITHUB

* doxygen: add TODO to WARN_IF_UNDOC_ENUM_VAL

* doxygen: set HTML_COLORSTYLE = LIGHT

* doxygen: set SHOW_HEADERFILE = NO

* docs: revert workaround for Doxygen inline function overload confusion

* doxygen: use SHOW_HEADERFILE in place of SHOW_USED_FILES

* Rename root fwd.hpp to doc.hpp and exclude from install commands

* Exclude doc headers from macro guard tests

Author: eramongodb

Doxyfile

@@ -1,36 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <doxygenlayout version="1.0">
-  <!-- Generated by doxygen 1.9.1 -->
+  <!-- Generated by doxygen 1.11.0 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title=""/>
     <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
+    <tab type="modules" visible="yes">
+      <tab type="modulelist" visible="yes" title="" intro=""/>
+      <tab type="modulemembers" visible="yes" title="" intro=""/>
+    </tab>
     <tab type="namespaces" visible="yes" title="">
       <tab type="namespacelist" visible="yes" title="" intro=""/>
       <tab type="namespacemembers" visible="yes" title="" intro=""/>
     </tab>
+    <tab type="concepts" visible="yes" title="">
+    </tab>
+    <tab type="interfaces" visible="yes" title="">
+      <tab type="interfacelist" visible="yes" title="" intro=""/>
+      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
+    </tab>
     <tab type="classes" visible="yes" title="">
       <tab type="classlist" visible="yes" title="" intro=""/>
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="modules" visible="yes" title="Groups" intro="Pages documenting groups of related entities."/>
+    <tab type="topics" visible="yes"  title="Groups" intro="Pages documenting groups of related entities."/>
     <tab type="pages" visible="yes" title="Topics" intro="Pages documenting topics related to the API."/>
-    <tab type="interfaces" visible="no" title="Unused">
-      <tab type="interfacelist" visible="yes" title="" intro=""/>
-      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="structs" visible="no" title="Unused">
+    <tab type="structs" visible="yes" title="">
       <tab type="structlist" visible="yes" title="" intro=""/>
-      <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
     </tab>
     <tab type="exceptions" visible="no" title="Unused">
       <tab type="exceptionlist" visible="yes" title="" intro=""/>
-      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
     </tab>
     <tab type="examples" visible="no" title="Unused" intro=""/>
@@ -39,11 +46,10 @@
   <!-- Layout definition for a class page -->
   <class>
     <briefdescription visible="no"/>
+    <includes visible="$SHOW_HEADERFILE"/>
     <detaileddescription title="Description"/>
-    <usedfiles visible="$SHOW_USED_FILES"/>
-    <includes visible="$SHOW_INCLUDE_FILES"/>
-    <inheritancegraph visible="$CLASS_GRAPH"/>
-    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <inheritancegraph visible="yes"/>
+    <collaborationgraph visible="yes"/>
     <memberdecl>
       <nestedclasses visible="yes" title=""/>
       <publictypes title=""/>
@@ -92,6 +98,7 @@
       <events title=""/>
     </memberdef>
     <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
     <authorsection visible="yes"/>
   </class>
 
@@ -104,6 +111,7 @@
       <constantgroups visible="yes" title=""/>
       <interfaces visible="yes" title=""/>
       <classes visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
       <structs visible="yes" title=""/>
       <exceptions visible="yes" title=""/>
       <typedefs title=""/>
@@ -112,6 +120,7 @@
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
+      <properties title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
     <memberdef>
@@ -122,24 +131,35 @@
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
+      <properties title=""/>
     </memberdef>
     <authorsection visible="yes"/>
   </namespace>
 
+  <!-- Layout definition for a concept page -->
+  <concept>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_HEADERFILE"/>
+    <definition visible="yes" title=""/>
+    <detaileddescription title=""/>
+    <authorsection visible="yes"/>
+  </concept>
+
   <!-- Layout definition for a file page -->
   <file>
     <briefdescription visible="no"/>
     <detaileddescription title="Description"/>
     <includes visible="$SHOW_INCLUDE_FILES"/>
-    <includegraph visible="$INCLUDE_GRAPH"/>
-    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <includegraph visible="yes"/>
+    <includedbygraph visible="yes"/>
     <sourcelink visible="yes"/>
     <memberdecl>
       <interfaces visible="yes" title=""/>
       <classes visible="yes" title=""/>
       <structs visible="yes" title=""/>
       <exceptions visible="yes" title=""/>
       <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
@@ -148,6 +168,7 @@
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
+      <properties title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
     <memberdef>
@@ -159,6 +180,7 @@
       <enums title=""/>
       <functions title=""/>
       <variables title=""/>
+      <properties title=""/>
     </memberdef>
     <authorsection/>
   </file>
@@ -167,12 +189,14 @@
   <group>
     <briefdescription visible="no"/>
     <detaileddescription title="Description"/>
-    <groupgraph visible="$GROUP_GRAPHS"/>
+    <groupgraph visible="yes"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
+      <modules visible="yes" title=""/>
       <dirs visible="yes" title=""/>
       <files visible="yes" title=""/>
       <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
       <classes visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
@@ -213,6 +237,25 @@
     <authorsection visible="yes"/>
   </group>
 
+  <!-- Layout definition for a C++20 module page -->
+  <module>
+    <briefdescription visible="yes"/>
+    <exportedmodules visible="yes"/>
+    <memberdecl>
+      <concepts visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <enums title=""/>
+      <typedefs title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups title=""/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdecl>
+      <files visible="yes"/>
+    </memberdecl>
+  </module>
+
   <!-- Layout definition for a directory page -->
   <directory>
     <briefdescription visible="no"/>

docs/DoxygenLayout.xml

@@ -11,7 +11,7 @@
 
 # The required Doxygen version.
 # The generated results are sensitive to the release version.
-our $doxygen_version_required = "1.9.1";
+our $doxygen_version_required = "1.11.0";
 
 # Allow specifying a custom Doxygen binary via the `$DOXYGEN_BINARY` environment variable.
 our $doxygen_binary = $ENV{DOXYGEN_BINARY} || "doxygen";

etc/generate-apidocs-from-tag.pl

@@ -15,7 +15,9 @@
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/
     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
     COMPONENT dev
-    FILES_MATCHING PATTERN "*.hpp"
+    FILES_MATCHING
+    PATTERN "*.hpp"
+    PATTERN "bsoncxx/doc.hpp" EXCLUDE
 )
 
 file(GLOB_RECURSE bsoncxx_include_headers

src/bsoncxx/include/CMakeLists.txt

@@ -20,10 +20,7 @@
 /// @file
 /// For documentation purposes only.
 ///
-/// This header is not intended to be includable.
-///
-/// @note This header is shadowed by @ref bsoncxx/v_noabi/bsoncxx/fwd.hpp per include directory
-/// search ordering.
+/// @note This header is not includable!
 ///
 
 ///

src/bsoncxx/include/bsoncxx/fwd.hpp renamed to src/bsoncxx/include/bsoncxx/doc.hpp

@@ -55,10 +55,11 @@ namespace builder {
 namespace basic {
 
 /// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::document::view_or_value doc)
-/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
-/// v_noabi::builder::concatenate_array is also declared in this scope.
 v_noabi::concatenate_doc concatenate(v_noabi::document::view_or_value doc);
 
+/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::array::view_or_value doc)
+v_noabi::concatenate_doc concatenate(v_noabi::array::view_or_value doc);
+
 }  // namespace basic
 }  // namespace builder
 }  // namespace bsoncxx

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/helpers.hpp

@@ -93,19 +93,25 @@ struct concatenate_array {
 ///
 /// @see bsoncxx::v_noabi::builder::concatenate_doc
 ///
-/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
-/// v_noabi::builder::concatenate_array is also declared in this scope.
-///
 BSONCXX_INLINE concatenate_doc concatenate(document::view_or_value doc) {
     return {std::move(doc)};
 }
 
-// Why is Doxygen unable to parse this overload correctly???
-// @cond DOXYGEN_DISABLE "warning: no matching file member found for ..."
+///
+/// Helper method to concatenate an array.
+///
+/// Use this with the document stream builder to merge an existing array's fields with a new
+/// document's.
+///
+/// @param array The array to concatenate.
+///
+/// @return concatenate_doc A concatenating struct.
+///
+/// @see bsoncxx::v_noabi::builder::concatenate_doc
+///
 BSONCXX_INLINE concatenate_array concatenate(array::view_or_value array) {
     return {std::move(array)};
 }
-// @endcond
 
 }  // namespace builder
 }  // namespace v_noabi
@@ -131,11 +137,12 @@ using ::bsoncxx::v_noabi::builder::concatenate;
 namespace bsoncxx {
 namespace builder {
 
-/// @ref bsoncxx::v_noabi::builder::concatenate
-/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
-/// v_noabi::builder::concatenate_array is also declared in this scope.
+/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::document::view_or_value doc)
 v_noabi::builder::concatenate_doc concatenate(v_noabi::document::view_or_value doc);
 
+/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::array::view_or_value doc)
+v_noabi::builder::concatenate_doc concatenate(v_noabi::array::view_or_value doc);
+
 }  // namespace builder
 }  // namespace bsoncxx
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/concatenate.hpp

@@ -35,7 +35,6 @@ set(bsoncxx_sources_v_noabi
 
 list(APPEND bsoncxx_sources
     ${bsoncxx_sources_v_noabi}
-    bsoncxx/fwd.cpp
 )
 list(TRANSFORM bsoncxx_sources PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
 set(bsoncxx_sources "${bsoncxx_sources}" PARENT_SCOPE)
@@ -71,7 +70,6 @@ endif()
 set_dist_list(src_bsoncxx_lib_DIST
     CMakeLists.txt
     ${bsoncxx_sources_v_noabi}
-    bsoncxx/fwd.cpp
     bsoncxx/v_noabi/bsoncxx/config/config.hpp.in
     bsoncxx/v_noabi/bsoncxx/config/private/config.hh.in
     bsoncxx/v_noabi/bsoncxx/config/private/postlude.hh

src/bsoncxx/lib/CMakeLists.txt

@@ -123,6 +123,7 @@ if(ENABLE_MACRO_GUARD_TESTS)
             "lib/*.hh" # Private headers.
             "test/*.hh" # Test headers.
         EXCLUDE_REGEXES
+            "include/bsoncxx/doc\.hpp" # Doc header.
             "(include|lib)/.*/(prelude|postlude)\.(hpp|hh)" # Macro guard headers.
             "(include|lib)/bsoncxx/v_noabi/bsoncxx/config/.*" # v_noabi config headers.
             "include/bsoncxx/v_noabi/bsoncxx/enums/.*" # v_noabi X-macro headers.

src/bsoncxx/lib/bsoncxx/fwd.cpp

@@ -15,7 +15,9 @@
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/
     DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
     COMPONENT dev
-    FILES_MATCHING PATTERN "*.hpp"
+    FILES_MATCHING
+    PATTERN "*.hpp"
+    PATTERN "mongocxx/doc.hpp" EXCLUDE
 )
 
 file(GLOB_RECURSE mongocxx_include_headers

src/bsoncxx/test/CMakeLists.txt

@@ -20,10 +20,7 @@
 /// @file
 /// For documentation purposes only.
 ///
-/// This header is not intended to be includable.
-///
-/// @note This header is shadowed by @ref mongocxx/v_noabi/mongocxx/fwd.hpp per include directory
-/// search ordering.
+/// @note This header is not includable!
 ///
 
 ///

src/mongocxx/include/CMakeLists.txt

@@ -111,7 +111,6 @@ set(mongocxx_sources_v_noabi
 
 list(APPEND mongocxx_sources
     ${mongocxx_sources_v_noabi}
-    mongocxx/fwd.cpp
 )
 list(TRANSFORM mongocxx_sources PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/")
 set(mongocxx_sources "${mongocxx_sources}" PARENT_SCOPE)
@@ -159,7 +158,6 @@ endif()
 set_dist_list(src_mongocxx_lib_DIST
     CMakeLists.txt
     ${mongocxx_sources_v_noabi}
-    mongocxx/fwd.cpp
     mongocxx/v_noabi/mongocxx/config/config.hpp.in
     mongocxx/v_noabi/mongocxx/config/private/config.hh.in
     mongocxx/v_noabi/mongocxx/config/private/postlude.hh

src/mongocxx/include/mongocxx/fwd.hpp renamed to src/mongocxx/include/mongocxx/doc.hpp

@@ -331,6 +331,7 @@ if(ENABLE_MACRO_GUARD_TESTS)
             "lib/*.hh" # Private headers.
             "test/*.hh" # Test headers.
         EXCLUDE_REGEXES
+            "include/mongocxx/doc\.hpp" # Doc header.
             "(include|lib)/.*/(prelude|postlude)\.(hpp|hh)" # Macro guard headers.
             "(include|lib)/mongocxx/v_noabi/mongocxx/config/.*" # v_noabi config headers.
             ".*_symbols.hh" # Symbol headers.