Boost C++ Libraries: Ticket #3707: doxygen commands have a typo in tests \detailed should be \details

Paul A. Bristow — Thu, 03 Dec 2009 15:19:02 GMT

Also line 15 test_lambda.cpp

/ \file test_lambda.hpp should be .cpp

Doxygen comments are wrong in boost/units/physical_dimensions.hpp

/ \file physical_dimensions.hpp / / \brief Physical dimensions according to the SI system / / \details This header includes all physical dimension headers for both base / derived dimensions. Base dimensions are extended to include plane and / solid angle for convenience.

doxygen would like a ; at the end of

BOOST_TYPEOF_NESTED_TYPEDEF_TPL(nested, pow(typeof_::make<Y>(), 0.0));

in static_rational_power.hpp

and boost\libs\units\test\test_output.cpp

\file test_output..cpp

was missing the filename.

Finally Doxygen warns:

I:/boost_trunk/libs/units/test/test_output.cpp:91: Warning: no matching file member found for const char * name_string(const boost::units::reduce_unit< boost::units::unit< boost::units::acceleration_dimension, my_system > >::type &) Possible candidates:

std::string name_string(const cgs::force &) std::string name_string(const custom1 &) std::string name_string(const unit< Dimension, System > &) std::string name_string(const scale< Base, Exponent > &) std::string name_string(const reduce_unit< cgs::acceleration >::type &) std::string name_string(const T &)

I:/boost_trunk/libs/units/test/test_output.cpp:92: Warning: no matching file member found for const char * symbol_string(const boost::units::reduce_unit< boost::units::unit< boost::units::acceleration_dimension, my_system > >::type &) Possible candidates:

std::string symbol_string(const cgs::force &) std::string symbol_string(const custom1 &) std::string symbol_string(const unit< Dimension, System > &) std::string symbol_string(const scale< Base, Exponent > &) std::string symbol_string(const reduce_unit< cgs::acceleration >::type &) std::string symbol_string(const T &)

It would seem that custom2 is not used? With it commented out (and other changes above corrected) Doxygen builds with no warnings.

I am finding a full Doxygen build a useful addition to the already helpful but still, for me, insufficient documentation for this massive package. If the files and parameters were documented (a massive task) it would be even better. A GSoC project?

Steven Watanabe — Sat, 05 Dec 2009 20:34:40 GMT

Replying to pbristow:

doxygen would like a ; at the end of

BOOST_TYPEOF_NESTED_TYPEDEF_TPL(nested, pow(typeof_::make<Y>(), 0.0));

in static_rational_power.hpp

A semicolon here is illegal. (gcc -pedantic warns about it, como --A rejects it.)

Steven Watanabe — Sat, 05 Dec 2009 20:43:34 GMT

Replying to pbristow:

Generating file member index... .cpp:11: Warning: Found unknown command `\detailed' I:/boost_1_41_0/libs/units/test/fail_quantity_assign.cpp:11:

<snip 56 others>

I:/boost_1_41_0/boost/units/dim.hpp:37: Warning: Found unknown command `\detailed'

Copy and paste is wonderful but ... ;-)

And a global grep to libs and boost unit replacing \detailed by \details gets rid of all these complaints. (There are a few others that I will investigate).

It would be better to remove it entirely because it is redundant. \details isn't available in doxygen 1.5 (which I am still using because somehow on my machine doxygen 1.6 was generating PNGs that IE8 couldn't display).

Steven Watanabe — Sat, 05 Dec 2009 20:46:13 GMT

Replying to pbristow:

Finally Doxygen warns:

<snip>

It would seem that custom2 is not used? With it commented out (and other changes above corrected) Doxygen builds with no warnings.

Commenting custom2 out may help Doxygen, but it will make the compiler very unhappy.

Paul A. Bristow — Mon, 07 Dec 2009 18:13:00 GMT

Replying to steven_watanabe:

Replying to pbristow:

Generating file member index... .cpp:11: Warning: Found unknown command `\detailed' I:/boost_1_41_0/libs/units/test/fail_quantity_assign.cpp:11:

<snip 56 others>

I:/boost_1_41_0/boost/units/dim.hpp:37: Warning: Found unknown command `\detailed'

Copy and paste is wonderful but ... ;-)

And a global grep to libs and boost unit replacing \detailed by \details gets rid of all these complaints. (There are a few others that I will investigate).

It would be better to remove it entirely because it is redundant. \details isn't available in doxygen 1.5 (which I am still using because somehow on my machine doxygen 1.6 was generating PNGs that IE8 couldn't display).

I recall using \details in 1.5 but I could be having a(other) senior moment ;-) But detailed comments can be really useful - provided there are some, of course.

(Aside: I am using Doxygen 1.6.1 without any problems - 1.6.0 crashed - and Dmitri van Heesch seems responsive to bug reports).

The other 'fixes' to warnings seem ill-advised, but I'd be happier with \detailed changed to \details, if applicable - and I'd be delighted if it applied long-term.

status changed; resolution set

Steven Watanabe — Mon, 07 Jun 2010 23:50:03 GMT

status new → closed
resolution → fixed

(In [62532]) Merge the units/autoprefix branch back to the trunk. Fixes #3660. Fixes #3707