Skip to content

Clear the four -Wdocumentation warnings - #1431

Merged
NAThompson merged 1 commit into
boostorg:developfrom
karpovantonme:docs/clear-wdocumentation
Sep 6, 2026
Merged

Clear the four -Wdocumentation warnings#1431
NAThompson merged 1 commit into
boostorg:developfrom
karpovantonme:docs/clear-wdocumentation

Conversation

@karpovantonme

Copy link
Copy Markdown
Contributor

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.

@NAThompson
NAThompson force-pushed the docs/clear-wdocumentation branch from a35a99b to 5aa7a23 Compare September 5, 2026 23:59
@NAThompson

Copy link
Copy Markdown
Collaborator

@karpovantonme : Rebased and am cycling CI. Should be merged shortly . . .

@NAThompson
NAThompson merged commit 3fad9e5 into boostorg:develop Sep 6, 2026
74 of 75 checks passed
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.

2 participants