Skip to content

Clear the four -Wdocumentation warnings - #1431

Open
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:docs/clear-wdocumentation
Open

Clear the four -Wdocumentation warnings#1431
karpovantonme wants to merge 1 commit into
boostorg:developfrom
karpovantonme:docs/clear-wdocumentation

Conversation

@karpovantonme

Copy link
Copy Markdown

Building the two aggregate headers with -Wdocumentation gives four warnings. This clears them.

$ clang++ -Wdocumentation -fsyntax-only -I include -std=c++14 agg.cpp
special_functions/lambert_w.hpp:781:14: warning: parameter '-term' not found in the function declaration
distributions/find_scale.hpp:63:7: warning: not a Doxygen trailing comment
distributions/find_scale.hpp:64:7: warning: not a Doxygen trailing comment
distributions/hyperexponential.hpp:57:11: warning: not a Doxygen trailing comment

Two different things behind them.

One real documentation mismatch

lambert_w.hpp:781

//! \param _z Lambert W argument z.
//! \param -term  -pow<18>(z) / 6402373705728000uLL
//! \param _k number of terms == initially 18

lambert_w0_small_z_series_term(T _z, T _term, int _k)

A hyphen where the other two have an underscore. Doxygen looks for a parameter named -term, does not find it, and _term ends up undocumented.

Three accidental Doxygen markers

//< and /*< are how Doxygen marks a trailing comment, and in these three places the sequence turns up by accident.

In find_scale.hpp it is inside commented-out debug output, where a line that used to begin with << quantile(...) became //<< quantile(...):

//cout << "z " << z << ", p " << p << ",  quantile(Dist(), p) "
//<< quantile(Dist(), p) << ", z - mean " << z - location

In hyperexponential.hpp it is the note on the unnamed namespace, namespace /*<unnamed>*/ {.

Neither is a documentation error, just a character sequence that reads as one. A space fixes both and the comments say the same thing.

I checked through boost/math/special_functions.hpp and boost/math/distributions.hpp, so this covers what those two pull in rather than every header in the library. -fsyntax-only stays clean after the change.

lambert_w: \param -term has a hyphen where the parameter is _term, so
Doxygen looks for a parameter that does not exist and leaves _term
undocumented.

find_scale and hyperexponential: three comments start with the character
sequence //< or /*<, which the compiler reads as a Doxygen trailing
comment marker. Both are accidents, one in commented-out debug output and
one in the /*<unnamed>*/ note on a namespace. A space is enough.
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