Merge pull request #1512 from NVIDIA/doxygen-fixes

help doxygen produce more useful output

Author: ericniebler

CMakeLists.txt

@@ -525,7 +525,7 @@ option(STDEXEC_BUILD_EXAMPLES "Build stdexec examples" ON)
 
 # Configure documentation
 if(STDEXEC_BUILD_DOCS)
-    add_subdirectory(docs)
+    add_subdirectory(docs EXCLUDE_FROM_ALL)
 endif()
 
 # Configure test executables

docs/CMakeLists.txt

@@ -23,9 +23,19 @@ file(GLOB_RECURSE STDEXEC_PUBLIC_HEADERS ${STDEXEC_PUBLIC_HEADER_DIR}/*.hpp)
 
 set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/include)
 set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/build/doxygen)
+set(DOXYGEN_EXCLUDE_DIR ${PROJECT_SOURCE_DIR}/include/execpools)
 set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
 set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
 set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+set(COMPILATION_DB_PATH ${PROJECT_SOURCE_DIR})
+
+# Find the location of stddef.h
+execute_process(COMMAND echo "#include <stddef.h>"
+                COMMAND c++ -xc -dI -E -
+                COMMAND grep -oP "/usr/.*(?=/stddef\.h)"
+                COMMAND tail -n 1
+                OUTPUT_VARIABLE STDDEF_INCLUDE_PATH OUTPUT_STRIP_TRAILING_WHITESPACE)
+message(STATUS "<stddef.h> include path: ${STDDEF_INCLUDE_PATH}")
 
 # Replace variables inside @@ with the current values
 configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
@@ -61,17 +71,18 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
                      ${SPHINX_EXECUTABLE} -b html
                      # Tell Breathe where to find the Doxygen output
                      -Dbreathe_projects.stdexec=${DOXYGEN_OUTPUT_DIR}/xml
-                   ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                     ${SPHINX_SOURCE} ${SPHINX_BUILD}
                    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                    DEPENDS
-                   # Other docs files you want to track should go here (or in some variable)
-                   ${STDEXEC_DOCUMENTATION_SOURCE_FILES}
-                   ${DOXYGEN_INDEX_FILE}
+                     # Other docs files you want to track should go here (or in some variable)
+                     ${STDEXEC_DOCUMENTATION_SOURCE_FILES}
+                     ${DOXYGEN_INDEX_FILE}
                    MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
                    COMMENT "Generating documentation with Sphinx")
 
 # Nice named target so we can run the job easily
-add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
+add_custom_target(docs ALL
+                  DEPENDS ${SPHINX_INDEX_FILE})
 
 # Add an install target to install the docs
 install(DIRECTORY ${SPHINX_BUILD} DESTINATION ${CMAKE_INSTALL_DOCDIR})

docs/Doxyfile.in

@@ -991,7 +991,6 @@ FILE_PATTERNS          = *.c \
                          *.cppm \
                          *.c++ \
                          *.c++m \
-                         *.java \
                          *.ii \
                          *.ixx \
                          *.ipp \
@@ -1006,33 +1005,7 @@ FILE_PATTERNS          = *.c \
                          *.hpp \
                          *.h++ \
                          *.ixx \
-                         *.l \
-                         *.cs \
-                         *.d \
-                         *.php \
-                         *.php4 \
-                         *.php5 \
-                         *.phtml \
-                         *.inc \
-                         *.m \
-                         *.markdown \
-                         *.md \
-                         *.mm \
-                         *.dox \
-                         *.py \
-                         *.pyw \
-                         *.f90 \
-                         *.f95 \
-                         *.f03 \
-                         *.f08 \
-                         *.f18 \
-                         *.f \
-                         *.for \
-                         *.vhd \
-                         *.vhdl \
-                         *.ucf \
-                         *.qsf \
-                         *.ice
+                         *.inc
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -1047,7 +1020,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = "@DOXYGEN_EXCLUDE_DIR@"
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1072,7 +1045,8 @@ EXCLUDE_PATTERNS       =
 # ANamespace::AClass, ANamespace::*Test
 
 EXCLUDE_SYMBOLS        = *__* \
-                         _*
+                         *::_* \
+                         std
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -2350,7 +2324,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2391,7 +2365,18 @@ 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             = STDEXEC_DOXYGEN_INVOKED
+PREDEFINED             =  __cplusplus=202302L \
+                          STDEXEC_DOXYGEN_INVOKED=1 \
+                          "STDEXEC_SYSTEM_CONTEXT_HEADER_ONLY=1" \
+                          "STDEXEC_SYSTEM_CONTEXT_INLINE=inline" \
+                          "STDEXEC_ATTRIBUTE(X)= " \
+                          "STDEXEC_AUTO_RETURN(...)=->decltype(auto){ return __VA_ARGS__; }" \
+                          "STDEXEC_MEMFN_DECL(...)=__VA_ARGS__" \
+                          "STDEXEC_CLANG()=1" \
+                          "STDEXEC_MSVC()=0" \
+                          "STDEXEC_GCC()=0" \
+                          "STDEXEC_NVHPC()=0" \
+                          "STDEXEC_EDG()=0"
 
 # 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
@@ -2821,3 +2806,11 @@ MSCGEN_TOOL            =
 # command).
 
 MSCFILE_DIRS           =
+
+# Use clang to parse the source code.
+CLANG_ASSISTED_PARSING = YES
+CLANG_DATABASE_PATH    = "@COMPILATION_DB_PATH@"
+CLANG_OPTIONS          = -isystem "@STDDEF_INCLUDE_PATH@" \
+                         -std=c++23 \
+                         -DSTDEXEC_DOXYGEN_INVOKED=1 \
+                         -DSTDEXEC_SYSTEM_CONTEXT_HEADER_ONLY=1

include/exec/__detail/__system_context_default_impl_entry.hpp

@@ -15,10 +15,10 @@
  */
 #pragma once
 
-// This file assumes STDEXEC_SYSTEM_CONTEXT_INLINE is defined before including it.
-// But clang-tidy doesn't know that, so we need to include the header that defines
-// it when clang-tidy is invoked.
-#if defined(STDEXEC_CLANG_TIDY_INVOKED)
+// This file assumes STDEXEC_SYSTEM_CONTEXT_INLINE is defined before including it. But clang-tidy
+// and doxygen don't know that, so we need to include the header that defines it when clang-tidy and
+// doxygen are invoked.
+#if defined(STDEXEC_CLANG_TIDY_INVOKED) || defined(STDEXEC_DOXYGEN_INVOKED)
 #  include "../system_context.hpp" // IWYU pragma: keep
 #endif
 

include/stdexec/__detail/__meta.hpp

@@ -729,9 +729,9 @@ namespace stdexec {
       _Cp<_Cs...> * = nullptr,
       _Dp<_Ds...> * = nullptr,
       _Tail *...__tail)
-      -> decltype(__mconcat_<(sizeof...(_Tail) == 0)>::__f(
+      -> __midentity<decltype(__mconcat_<(sizeof...(_Tail) == 0)>::__f(
         static_cast<__types<_Ts..., _As..., _Bs..., _Cs..., _Ds...> *>(nullptr),
-        __tail...));
+        __tail...))>;
   };
 
   template <>

include/stdexec/__detail/__variant.hpp

@@ -22,6 +22,7 @@
 #include <cstddef>
 #include <memory>
 #include <new>
+#include <utility>
 
 /********************************************************************************/
 /* NB: The variant type implemented here default-constructs into the valueless  */