Christopher M. Punches
50b95fb729
dpm_core carries a namespace block saying what it holds and why its members keep external linkage while staying off the export table. Each unnamed namespace says its contents are private to that translation unit, and the one in the info module says why it has to be unnamed there: a module is built without hidden visibility or a version script, so a helper with external linkage would reach that module's exports. The three opaque handles in the public header were undocumented. What documentation they had came from the struct definitions in include/internal, which a consumer never sees. EXTRACT_ANON_NSPACES was off, so the documentation on every file-private helper was written and discarded. Doxygen also capitalizes the first letter of a brief, which turned libdpm-core.so into Libdpm-core.so wherever a brief opened with it; those are reworded. Bare references to the library are replaced with the artifact name throughout, including three in the info module's output. The cli_info_version regex follows.
104 lines
4.2 KiB
CMake
104 lines
4.2 KiB
CMake
# ---------------------------------------------------------------------
|
|
# Code reference (Doxygen) — optional 'docs' target
|
|
#
|
|
# The output paths come from the top-level file, which defines them
|
|
# before adding this directory so that each is written in one place.
|
|
# ---------------------------------------------------------------------
|
|
option(DPM_DOCS_HTML "Generate the code reference in HTML" ON)
|
|
option(DPM_DOCS_PDF "Generate the code reference as PDF (requires LaTeX)" ON)
|
|
|
|
find_package(Doxygen)
|
|
if(DOXYGEN_FOUND)
|
|
# Doxygen and LaTeX both work in scratch space under docs/tmp. The
|
|
# finished document is copied up into docs/, so the directory a user
|
|
# opens holds documentation and nothing else.
|
|
set(DOXYGEN_OUTPUT_DIRECTORY ${DPM_DOCS_TMP_DIR})
|
|
set(DOXYGEN_EXTRACT_ALL YES)
|
|
set(DOXYGEN_EXTRACT_STATIC YES)
|
|
|
|
# Helpers private to a translation unit live in unnamed namespaces,
|
|
# whose contents Doxygen drops unless this is on. Without it their
|
|
# documentation is written and never reaches the output.
|
|
set(DOXYGEN_EXTRACT_ANON_NSPACES YES)
|
|
set(DOXYGEN_QUIET YES)
|
|
set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
|
|
set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
|
|
|
|
if(DPM_DOCS_HTML)
|
|
set(DOXYGEN_GENERATE_HTML YES)
|
|
else()
|
|
set(DOXYGEN_GENERATE_HTML NO)
|
|
endif()
|
|
|
|
if(DPM_DOCS_PDF)
|
|
set(DOXYGEN_GENERATE_LATEX YES)
|
|
set(DOXYGEN_USE_PDFLATEX YES)
|
|
set(DOXYGEN_PDF_HYPERLINKS YES)
|
|
else()
|
|
set(DOXYGEN_GENERATE_LATEX NO)
|
|
endif()
|
|
|
|
# The prose documents, each rendered as its own page in the generated
|
|
# reference. Named one per line so the set of documents reaching the
|
|
# output is stated here instead of implied by a directory.
|
|
set(DPM_DOC_PAGES
|
|
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/OVERVIEW.md
|
|
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/DESIGN.md
|
|
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/CONSUMERS.md
|
|
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/MODULES.md
|
|
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/BUILD.md
|
|
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/DOCUMENTATION.md
|
|
)
|
|
|
|
# Two kinds of input: include/ and src/ supply the API and internals
|
|
# reference extracted from the source, DPM_DOC_PAGES supplies the
|
|
# prose pages.
|
|
#
|
|
# One target, so `cmake --build <dir> --target docs` is the whole
|
|
# procedure and the IDE lists a single entry for it. The commands
|
|
# below run after Doxygen and place the finished documents.
|
|
doxygen_add_docs(docs
|
|
${CMAKE_SOURCE_DIR}/include
|
|
${CMAKE_SOURCE_DIR}/src
|
|
${DPM_DOC_PAGES}
|
|
COMMENT "Generating the reference with Doxygen"
|
|
)
|
|
|
|
if(DPM_DOCS_PDF)
|
|
find_program(PDFLATEX_EXECUTABLE pdflatex)
|
|
if(PDFLATEX_EXECUTABLE)
|
|
add_custom_command(TARGET docs POST_BUILD
|
|
COMMAND make -C ${DPM_DOCS_TMP_DIR}/latex
|
|
COMMAND ${CMAKE_COMMAND} -E rm -rf
|
|
${DPM_DOCS_PDF_DIR}
|
|
COMMAND ${CMAKE_COMMAND} -E copy
|
|
${DPM_DOCS_TMP_DIR}/latex/refman.pdf
|
|
${DPM_DOCS_PDF_DIR}/dpm-core-${PROJECT_VERSION}.pdf
|
|
COMMENT "Compiling the PDF reference"
|
|
)
|
|
else()
|
|
message(WARNING "DPM_DOCS_PDF is ON but pdflatex was not found; no PDF will be produced")
|
|
endif()
|
|
endif()
|
|
|
|
if(DPM_DOCS_HTML)
|
|
add_custom_command(TARGET docs POST_BUILD
|
|
COMMAND ${CMAKE_COMMAND} -E rm -rf
|
|
${DPM_DOCS_HTML_DIR}
|
|
COMMAND ${CMAKE_COMMAND} -E copy_directory
|
|
${DPM_DOCS_TMP_DIR}/html
|
|
${DPM_DOCS_HTML_DIR}
|
|
COMMENT "Placing the HTML reference"
|
|
)
|
|
endif()
|
|
|
|
# Doxygen keeps output files it judges unchanged, so a run over a
|
|
# populated scratch directory can carry pages forward from an earlier
|
|
# one. Removing it here means the next run regenerates everything,
|
|
# and leaves docs/ holding the finished documents alone.
|
|
add_custom_command(TARGET docs POST_BUILD
|
|
COMMAND ${CMAKE_COMMAND} -E rm -rf ${DPM_DOCS_TMP_DIR}
|
|
COMMENT "Clearing the generators' scratch directory"
|
|
)
|
|
endif()
|
