[doc] Document the actual template parameters of the projections - #1485
Open
karpovantonme wants to merge 1 commit into
Open
[doc] Document the actual template parameters of the projections#1485karpovantonme wants to merge 1 commit into
karpovantonme wants to merge 1 commit into
Conversation
Every projection class in srs/projections/proj is `template <typename T, typename Parameters>`, but the Doxygen block above each one still documents `Geographic` and `Cartesian`, the parameters these classes took before ddce41f (Apr 2017) moved the internal representations. `T` has been undocumented since. All 152 blocks in 99 headers were byte-identical and every one is followed by `template <typename T, typename Parameters>`, so this is a straight replacement. The wording for `T` is taken from srs/projections/impl/base_dynamic.hpp, which already documents the same type as "calculation type". Comments only.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every projection class in
srs/projections/projis declared asbut the Doxygen block above it documents parameters the class does not have:
GeographicandCartesianare the template parameters these classes took before ddce41f (Apr 2017, "[projections] Move back the internal projections representations into..."). Since then the classes take the calculation type and the parameters type, andThas been undocumented while two names that no longer exist are documented instead. These blocks carry\ingroup projections, so they are published documentation, not internal notes.This replaces the two stale lines with one for
T:Comments only — no code touched.
Why this is safe to do in one sweep
All 152 blocks across the 99 headers are byte-identical, and every single one is followed by
template <typename T, typename Parameters>. I checked both before touching anything:and a script confirmed 0 blocks with a different shape and 0 blocks not followed by
template <typename T, ...>. After the change,grep -rn "tparam Geographic\|tparam Cartesian" include/returns nothing.The wording for
Tis not invented —srs/projections/impl/base_dynamic.hppalready documents the same type as\tparam CT calculation type, andsrs/projection.hppandsrs/transformation.hppuse "calculation type used internally". I kept it to "calculation type" to match the closest sibling. Happy to switch to a different phrasing if you prefer one.One thing I left alone
The same sweep flags a few other Doxygen blocks elsewhere in the library where a documented
\tparamor\paramname is not in the signature — for examplepolicies/compare.hpp:375documentsGeometryfor a<Point, Dimension, CSTag>template, andalgorithms/simplify.hpp:78has a\tparam thethat looks like a line got mangled. They are unrelated to the projections, so I kept them out of this PR. If you want them looked at, say so in a comment and I will send a separate one — or tell me they are intentional and I will leave them be.