[doc] Fix \tparam names that do not match the declaration

[karpovantonme]

Four Doxygen blocks name a template parameter the declaration below them does not have.

File	Documented	Declared
algorithms/detail/overlay/clip_linestring.hpp:43	B, P	Box, Point
algorithms/simplify.hpp:82	the	Point
strategies/azimuth.hpp:27	CalculationType	only CSTag exists
strategies/transform.hpp:41	CoordinateSystemTag, CoordinateSystem, D, Point	the eight numbered ones

Two of these are interesting beyond a rename.

simplify.hpp reads \tparam the enclosed point type, with the name left out, so Doxygen takes the as the parameter name and the description becomes "enclosed point type" attached to a parameter that does not exist.

transform.hpp documents pairs in one line each:

\tparam CoordinateSystemTag 1,2 coordinate system tags
\tparam CoordinateSystem 1,2 coordinate system
\tparam D 1, 2 dimension
\tparam Point 1, 2 point type

The intent is clear to a human and invisible to Doxygen, which reads four names none of which exist, and leaves all eight real parameters undocumented. Split into eight lines.

Which one is source and which is target is not a guess: transform(Geometry1 const& geometry1, Geometry2& geometry2) takes the first by const reference and the second mutable, and select_strategy passes Geometry1's traits into the odd positions.

azimuth.hpp simply lists one parameter too many, so that line is gone.

Not included

The same sweep flags twelve more, and they are a different kind: the block documents parameters that belong to a member function rather than to the class, e.g. detail/not.hpp documents Geometry1/Geometry2 from apply on a class templated only on Policy, and the pythagoras distance strategies do the same with Point1/Point2. Fixing those means deciding where the documentation should live, which is yours to make rather than mine. Point at any of them and I will send a follow-up.

Checks

Comments only, no declaration touched. The check reported 24 before and 16 after, and the sixteen left are exactly the group described above.

Found with a small tool that pulls every \param and \tparam name out of a Doxygen block and compares it against the declaration that follows, then re-run afterwards to confirm the count moved by exactly the number of edits.

[barendgehrels]

Thanks! I think this include the other PR #1485
So we only need to review this one? If so, can you close the other one?

[karpovantonme]

Yes, this one includes 1485 -- I diffed them, all 251 added lines of 1485 are in here, plus 11 more \tparam lines in clip_linestring.hpp and simplify.hpp that turned up in a second pass

Closing 1485 now, so this is the only one to review

[tinko92]

Thanks for the PR! Your commit message mentions tool use, could you disclose the tools used here for reproducibility?

Since this is a lot to review manually, I think tooling-based validation is helpful here. The clang-doc tool in LLVM can parse both template declarations and doxygen and generates yaml-output documenting both the tparam-lines and the actual template parameters in a strucured format. This yaml-output can then be queried for discrepancies using https://github.com/mikefarah/yq .

git checkout doc/tparam-names-match-declaration
git log --name-only --pretty="" develop..HEAD | sort | uniq | sed 's/include\//#include </g' | sed 's/$/>/g' > headers.cpp && echo "int main() {}" >> headers.cpp
clang-doc --format=yaml --output=clang-doc-geometry --doxygen --extra-arg=-I$HOME/dev/boost headers.cpp
git checkout develop
clang-doc --format=yaml --output=clang-doc-geometry-develop --doxygen --extra-arg=-I$HOME/dev/boost headers.cpp
for file in clang-doc-geometry/*.yaml; do sh match.sh $file ; done > discrepancies.txt
for file in clang-doc-geometry-develop/*.yaml; do sh match.sh $file ; done > discrepancies-develop.txt
diff discrepancies-develop.txt discrepancies.txt | grep '^>'

Output (see comment):

> /Users/tinko/dev/boost/boost/geometry/srs/projections/proj/ob_tran.hpp:581: boost::geometry::projections::ob_tran_static: template [StaticParameters, T, Parameters], doxygen \tparam [T, Parameters]

The above grep expression is meant to only match lines where the PR changes tparam comments and it still does not match the C++ declaration.

I think, besides the two commented comments, this PR is correct and can be merged after addressing.

LLM disclosure: I used Codex with model GPT 5.6 Sol to harden the query expression in the match.sh script after an initial draft against the full list of yaml files generated by clang-doc.

Match script used:
match.sh

@barendgehrels The above verification workflow runs reasonably fast (generates roughly 14,000 yaml files, though), clang-doc and yq are both open source tools. Running it on the broader library reveals more mismatches (for template parameters only: 30 where tparam comments exist but do not exactly match the template parameters, 97 where template parameters exist but no tparam comments). Do you think, we want a CI-action for this to catch future implementation/documentation drift? It probably extends straightforwardly to function arguments and other things with structured doxygen documentation too. I could create a PR next week which tolerates existing mismatches but fails on new ones.

[karpovantonme]

First off, thank you 🙏🏼 You read my PR and built a checker to validate the whole diff against develop, and then took it further and asked whether the project wants this permanently. Seeing it turn into a CI proposal is the best outcome I could have hoped for

Tools, since you asked. The finder is driftkit, a small thing I wrote and keep as a repo, Python and stdlib only. I built it with Claude Opus 5 . The tool gives me a list of candidates, and I read each one against the declaration before it becomes a diff, which is why the not included section of this PR exists at all

Your ob_tran_static catch is a class mine does not see yet. By construction the doxygen check has two findings: a \param name that is not in the argument list, and a \tparam name that is not among the template parameters. Both are "the comment claims something the code does not have". Yours is the other way round, there in the code and never declared, and I have not built that side. Worth trying to add, so thanks again, this is useful to me too

And it lines up with your own numbers - the 30 mismatched ones are what driftkit was pointed at from the start, the 97 missing ones it has not been looking for

Both review points are in:

• ob_tran.hpp, added \tparam StaticParameters first, in declaration order
• tmerc.hpp, moved the commented-out approximate implementation below the real declaration so the block binds to it. Same lines reordered, nothing else changed

I checked the rest of srs/projections/proj for the same detached-block shape and tmerc.hpp is the only one. Two candidates in isea.hpp turned out to be plain /* */ comments in detail, not doxygen

On the CI action, yes, and "tolerate existing, fail on new" is the right shape. And a hard gate on 127 findings never gets switched on so clang-doc reading the real declarations is a much better base than regular expressions over headers, especially for the missing half, where you need the full template parameter list rather than the names that happen to be in the comment. Happy to feed you anything useful from my end 🙌🏼

[barendgehrels]

👍 👍 👍
I cannot react right now on the follow up - bit will approve this PR, thanks a lot (and for the after work you both)

[tinko92]

The check outlined in the previous comment completes successfully with the third commit.

[tinko92]

Squashed and merged due to having two approvals and passing CI.