Skip to content

[doc] Fix the template parameter names in three Doxygen blocks - #443

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

[doc] Fix the template parameter names in three Doxygen blocks#443
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:doc-tparam-names

Conversation

@karpovantonme

Copy link
Copy Markdown

Three Doxygen blocks name a template parameter the declaration does not have. Comments only.

accumulators/count.hpp

  @tparam T C++ builtin arithmetic type (integer or floating point).
  @tparam ThreadSafe Set to true to make increments and adds thread-safe.
*/
template <class ValueType, bool ThreadSafe>
class count {

ThreadSafe is right, T should be ValueType.

weight.hpp and sample.hpp

  @tparam Underlying arithmetic type.
*/
template <class T>
struct weight_type {

"Underlying" reads as an adjective here, but Doxygen takes the first word after @tparam as the name, so it documents a parameter called Underlying and reports T as undocumented. Inserting the name leaves the sentence as it was: @tparam T Underlying arithmetic type. Same in sample.hpp.

I checked the rest of accumulators/ and axis/ for the same thing; count.hpp is the only one there, the axis blocks all match their declarations.

Not included

A sweep of the whole library also flags axis/traits.hpp, histogram.hpp, indexed.hpp, unsafe_access.hpp and the five utility/*_interval.hpp headers, but every one of those is my parser failing on auto&& parameters and on operator(), not a real mismatch — I read them and the docs are correct. Mentioning it so nobody repeats the check and thinks there is more here.

- accumulators::count documents @tparam T, the parameter is ValueType.
  ThreadSafe next to it is right.
- weight_type and sample_type document @tparam Underlying, which reads
  as an adjective but Doxygen takes as the parameter name, so it
  documents a parameter called "Underlying" and reports T as
  undocumented. Adding the name keeps the wording intact.
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