Skip to content

[doc] Document the actual template parameters of the projections - #1485

Open
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:doc-tparam-projections
Open

[doc] Document the actual template parameters of the projections#1485
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:doc-tparam-projections

Conversation

@karpovantonme

Copy link
Copy Markdown

Every projection class in srs/projections/proj is declared as

template <typename T, typename Parameters>
struct aea_ellipsoid : public detail::aea::base_aea_ellipsoid<T, Parameters>

but the Doxygen block above it documents parameters the class does not have:

        \tparam Geographic latlong point type
        \tparam Cartesian xy point type
        \tparam Parameters parameter type

Geographic and Cartesian are 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, and T has 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:

        \tparam T calculation type
        \tparam Parameters parameter type

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:

$ grep -rn "tparam Geographic\|tparam Cartesian\|tparam Parameters" include/boost/geometry/srs/ | sed 's/.*tparam/tparam/' | sort | uniq -c
 152 tparam Cartesian xy point type
 152 tparam Geographic latlong point type
 152 tparam Parameters parameter type
   1 tparam Parameters default dynamic tag or static projection parameters

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 T is not invented — srs/projections/impl/base_dynamic.hpp already documents the same type as \tparam CT calculation type, and srs/projection.hpp and srs/transformation.hpp use "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 \tparam or \param name is not in the signature — for example policies/compare.hpp:375 documents Geometry for a <Point, Dimension, CSTag> template, and algorithms/simplify.hpp:78 has a \tparam the that 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.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant