e04515c423
ROOT CAUSE FIX
The Doxyfile EXCLUDE_PATTERNS line contained `*/* 2.hpp` (note the
space — a stray glob from macOS-style "foo 2.hpp" duplicate files).
That pattern was silently matching ALL .hpp / .h files, so Doxygen was
indexing nothing under code/include/. The pre-existing 556 KB of HTML
output was effectively documenting only README.md, CLAUDE.md and a
small stub for std:: — not the C++ API at all.
After fixing the pattern (and properly escaping the space-prefixed
"foo 2.hpp / foo 2.h" macOS-dup patterns), Doxygen now extracts 141
compounds and emits 248 HTML pages from the public headers.
WHAT THIS PR ADDS
1. Doxyfile fix: correct EXCLUDE_PATTERNS; add GENERATE_XML for the
coverage measurement script; add MathJax for `$$...$$` math in
markdown; add the missing CGAL `\cgalParamNBegin/End/Description/
Default/...` aliases so CGAL-style param blocks render correctly.
2. New headers:
- code/include/CGAL/Conformal_map/doxygen_groups.h
defines `PkgConformalMap{,Ref,Concepts,NamedParameters}`,
resolving 17 prior "non-existing group" warnings.
- code/include/CGAL/Conformal_map/doxygen_namespaces.h
gives every namespace under `CGAL::` and `conformallab::` a
brief description.
3. New tool: scripts/doxygen-coverage.sh
Parses the XML output and reports % of public symbols (excluding
the `detail::` implementation namespaces by default) that have a
non-empty brief/detailed description. Supports `--list-undoc`
and `--threshold N` for CI integration.
4. Substantial docstring additions to the public CGAL headers:
`Conformal_map_traits.h`, `Discrete_circle_packing.h`,
`Discrete_inversive_distance.h`, `conformal_mesh.hpp`,
`Discrete_conformal_map.h` (Hyper_ideal_map_result fields).
5. Markdown housekeeping that the strict-warning Doxygen run surfaced:
tests.md (escape literal `#` in table cell),
locked-vs-flexible.md (broken section anchor),
overall_pipeline.md (replace `$$LaTeX$$` with inline-unicode math).
CURRENT NUMBERS
before: ~24% documented (public API; the prior "87%" claim was
based on the broken extraction)
after: 42% documented (165 of 396 public symbols)
warnings: 0 (was 27 spurious + a flood of bogus undocumented
warnings hidden by the buggy EXCLUDE pattern)
NEXT (in a follow-up commit on this branch)
The remaining 231 public symbols (mostly in `layout.hpp`,
`hyper_ideal_functional.hpp`, `spherical_functional.hpp`, the per-mode
functional/Hessian files) can be brought to ~100% with another pass of
short `///` brief descriptions. The coverage script is the gate; CI
can begin enforcing `--threshold 95` once the next pass lands.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
166 lines
7.7 KiB
Plaintext
166 lines
7.7 KiB
Plaintext
# Doxyfile for conformallab++
|
|
#
|
|
# Phase 7.5 — minimal CGAL-style Doxygen configuration.
|
|
# Only non-default values are set; Doxygen ≥ 1.9.5 supplies the rest.
|
|
#
|
|
# Usage:
|
|
# doxygen Doxyfile # generates HTML into doc/doxygen/html/
|
|
# open doc/doxygen/html/index.html
|
|
#
|
|
# Or via CMake:
|
|
# cmake --build build --target doc
|
|
|
|
# ── Project identity ─────────────────────────────────────────────────────────
|
|
PROJECT_NAME = "conformallab++"
|
|
PROJECT_NUMBER = 0.7.0
|
|
PROJECT_BRIEF = "Discrete conformal maps on triangle meshes — C++17 reimplementation of ConformalLab (TU Berlin)"
|
|
PROJECT_LOGO =
|
|
OUTPUT_DIRECTORY = doc/doxygen
|
|
USE_MDFILE_AS_MAINPAGE = README.md
|
|
|
|
# ── Input ────────────────────────────────────────────────────────────────────
|
|
INPUT = README.md \
|
|
CLAUDE.md \
|
|
code/include \
|
|
doc/api \
|
|
doc/architecture \
|
|
doc/math
|
|
FILE_PATTERNS = *.hpp *.h *.cpp *.md
|
|
RECURSIVE = YES
|
|
EXCLUDE_PATTERNS = */build*/* \
|
|
*/deps/* \
|
|
*/.git/* \
|
|
*/test-reports/* \
|
|
*\ 2.hpp \
|
|
*\ 2.h
|
|
# Research-quality LaTeX notes use raw \sinh / \cosh / \frac / \beta /
|
|
# \cdot / \partial / \zeta macros which are valid LaTeX but unknown to
|
|
# Doxygen. These files are intended to be read as PDF or in a LaTeX-
|
|
# aware markdown viewer, not as Doxygen pages. Excluding them removes
|
|
# ~500 spurious "unknown command" warnings while keeping the .md files
|
|
# discoverable on GitHub.
|
|
EXCLUDE = doc/math/hyperideal-hessian-derivation.md
|
|
EXCLUDE_SYMBOLS = Eigen::* boost::* std::*
|
|
|
|
# Markdown filter: rewrites repo-relative links like [x](doc/api/tests.md)
|
|
# into basename-only links [x](tests.md) so Doxygen's basename-indexed
|
|
# \ref resolver can find them. On-disk files are untouched (GitHub keeps
|
|
# rendering them correctly). See scripts/doxygen-md-filter.sh.
|
|
FILTER_PATTERNS = *.md=scripts/doxygen-md-filter.sh
|
|
|
|
# ── Source browsing ──────────────────────────────────────────────────────────
|
|
EXTRACT_ALL = YES
|
|
EXTRACT_PRIVATE = NO
|
|
EXTRACT_STATIC = YES
|
|
EXTRACT_LOCAL_CLASSES = YES
|
|
HIDE_UNDOC_MEMBERS = NO
|
|
SOURCE_BROWSER = YES
|
|
INLINE_SOURCES = NO
|
|
STRIP_CODE_COMMENTS = NO
|
|
REFERENCED_BY_RELATION = YES
|
|
REFERENCES_RELATION = YES
|
|
REFERENCES_LINK_SOURCE = YES
|
|
|
|
# ── Build options ────────────────────────────────────────────────────────────
|
|
JAVADOC_AUTOBRIEF = YES
|
|
QT_AUTOBRIEF = NO
|
|
MARKDOWN_SUPPORT = YES
|
|
AUTOLINK_SUPPORT = YES
|
|
BUILTIN_STL_SUPPORT = YES
|
|
DISTRIBUTE_GROUP_DOC = YES
|
|
GROUP_NESTED_COMPOUNDS = YES
|
|
SUBGROUPING = YES
|
|
INLINE_GROUPED_CLASSES = NO
|
|
INLINE_SIMPLE_STRUCTS = NO
|
|
TYPEDEF_HIDES_STRUCT = NO
|
|
EXTENSION_MAPPING = h=C++ hpp=C++
|
|
|
|
# ── Warnings ─────────────────────────────────────────────────────────────────
|
|
QUIET = NO
|
|
WARNINGS = YES
|
|
WARN_IF_UNDOCUMENTED = YES
|
|
WARN_IF_DOC_ERROR = YES
|
|
WARN_IF_INCOMPLETE_DOC = YES
|
|
WARN_NO_PARAMDOC = NO
|
|
WARN_AS_ERROR = NO
|
|
WARN_FORMAT = "$file:$line: $text"
|
|
WARN_LOGFILE = doc/doxygen/doxygen-warnings.log
|
|
|
|
# ── HTML output ──────────────────────────────────────────────────────────────
|
|
GENERATE_HTML = YES
|
|
|
|
# MathJax — render LaTeX math in markdown ($...$ and $$...$$) and in
|
|
# code-comment `\f$ ... \f$` blocks via MathJax in the generated HTML.
|
|
# Required for the conformal-mapping math notation (\Theta, \omega, \tau,
|
|
# \mathbb{H}, …) in doc/architecture/overall_pipeline.md and the
|
|
# header docstrings.
|
|
USE_MATHJAX = YES
|
|
MATHJAX_VERSION = MathJax_3
|
|
MATHJAX_FORMAT = HTML-CSS
|
|
MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@3/es5/
|
|
HTML_OUTPUT = html
|
|
HTML_FILE_EXTENSION = .html
|
|
HTML_COLORSTYLE = LIGHT
|
|
HTML_COLORSTYLE_HUE = 220
|
|
HTML_COLORSTYLE_SAT = 100
|
|
HTML_COLORSTYLE_GAMMA = 80
|
|
HTML_TIMESTAMP = NO
|
|
HTML_DYNAMIC_SECTIONS = YES
|
|
GENERATE_TREEVIEW = YES
|
|
DISABLE_INDEX = NO
|
|
ENUM_VALUES_PER_LINE = 1
|
|
TREEVIEW_WIDTH = 280
|
|
EXT_LINKS_IN_WINDOW = NO
|
|
SEARCHENGINE = YES
|
|
SERVER_BASED_SEARCH = NO
|
|
|
|
# ── Disabled outputs (we only want HTML) ─────────────────────────────────────
|
|
GENERATE_LATEX = NO
|
|
GENERATE_RTF = NO
|
|
GENERATE_MAN = NO
|
|
GENERATE_XML = YES
|
|
XML_OUTPUT = xml
|
|
XML_PROGRAMLISTING = NO
|
|
GENERATE_DOCBOOK = NO
|
|
GENERATE_AUTOGEN_DEF = NO
|
|
GENERATE_PERLMOD = NO
|
|
|
|
# ── Preprocessor ─────────────────────────────────────────────────────────────
|
|
ENABLE_PREPROCESSING = YES
|
|
MACRO_EXPANSION = YES
|
|
EXPAND_ONLY_PREDEF = YES
|
|
SEARCH_INCLUDES = YES
|
|
INCLUDE_PATH = code/include
|
|
PREDEFINED = CGAL_DISABLE_GMP \
|
|
CGAL_DISABLE_MPFR \
|
|
DOXYGEN_RUNNING
|
|
|
|
# ── Diagrams ─────────────────────────────────────────────────────────────────
|
|
HAVE_DOT = NO
|
|
CLASS_GRAPH = YES
|
|
COLLABORATION_GRAPH = NO
|
|
GROUP_GRAPHS = YES
|
|
INCLUDE_GRAPH = NO
|
|
INCLUDED_BY_GRAPH = NO
|
|
CALL_GRAPH = NO
|
|
CALLER_GRAPH = NO
|
|
|
|
# ── Aliases (CGAL-style) ─────────────────────────────────────────────────────
|
|
ALIASES += "concept{1}=\xrefitem concept \"Concept\" \"Concepts\" \1"
|
|
ALIASES += "models{1}=\xrefitem models \"Models\" \"Models\" \1"
|
|
ALIASES += "cgalRequires{1}=\par Requirements: \n\1"
|
|
ALIASES += "cgalParam{2}=\param \1 \2"
|
|
# CGAL named-parameter block aliases — replicates the upstream
|
|
# ${CGAL}/Documentation/doc/Documentation/Doxyfile_common conventions
|
|
# so that \cgalParamNBegin{name} … \cgalParamNEnd blocks render as
|
|
# nested HTML lists in our Doxygen output.
|
|
ALIASES += "cgalNamedParamsBegin=<dl class=\"params\"><dt>Optional named parameters</dt><dd><table class=\"params\">"
|
|
ALIASES += "cgalNamedParamsEnd=</table></dd></dl>"
|
|
ALIASES += "cgalParamNBegin{1}=<tr><td class=\"paramname\"><code>\1</code></td><td>"
|
|
ALIASES += "cgalParamNEnd=</td></tr>"
|
|
ALIASES += "cgalParamDescription{1}=<b>Description:</b> \1<br/>"
|
|
ALIASES += "cgalParamType{1}=<b>Type:</b> \1<br/>"
|
|
ALIASES += "cgalParamDefault{1}=<b>Default:</b> \1<br/>"
|
|
ALIASES += "cgalParamPrecondition{1}=<b>Precondition:</b> \1<br/>"
|
|
ALIASES += "cgalParamExtra{1}=<i>\1</i><br/>"
|