From a343f41513811fbb24eca9c1d57624b957115eaf Mon Sep 17 00:00:00 2001 From: Eric Niebler Date: Sun, 30 Mar 2025 19:05:30 -0700 Subject: [PATCH] help doxygen produce more useful output --- CMakeLists.txt | 2 +- docs/CMakeLists.txt | 21 +++++-- docs/Doxyfile.in | 57 ++++++++----------- .../__system_context_default_impl_entry.hpp | 8 +-- include/stdexec/__detail/__meta.hpp | 4 +- include/stdexec/__detail/__variant.hpp | 1 + 6 files changed, 49 insertions(+), 44 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index fecdbdeab..8e29cfed0 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 723c73a9a..b3ff4f4f7 100644 --- a/docs/CMakeLists.txt +++ b/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 " + 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 " 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}) \ No newline at end of file diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 5652c22d0..abd193986 100644 --- a/docs/Doxyfile.in +++ b/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 diff --git a/include/exec/__detail/__system_context_default_impl_entry.hpp b/include/exec/__detail/__system_context_default_impl_entry.hpp index 7de472d15..394264162 100644 --- a/include/exec/__detail/__system_context_default_impl_entry.hpp +++ b/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 diff --git a/include/stdexec/__detail/__meta.hpp b/include/stdexec/__detail/__meta.hpp index b474f9e62..25a2103c8 100644 --- a/include/stdexec/__detail/__meta.hpp +++ b/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::__f( static_cast<__types<_Ts..., _As..., _Bs..., _Cs..., _Ds...> *>(nullptr), - __tail...)); + __tail...))>; }; template <> diff --git a/include/stdexec/__detail/__variant.hpp b/include/stdexec/__detail/__variant.hpp index a962bdf3d..bb24f409f 100644 --- a/include/stdexec/__detail/__variant.hpp +++ b/include/stdexec/__detail/__variant.hpp @@ -22,6 +22,7 @@ #include #include #include +#include /********************************************************************************/ /* NB: The variant type implemented here default-constructs into the valueless */