Subject: [Boost-docs] Using Doxygen comments to specify conditions on template parameters of a class or struct
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-11-20 18:49:52
I had assumed that I could use the Quickbook toolchain to Doxygen comment document requirements for
*template parameters* just as for functions.
This works as expected and the text "Preconditions: No preconditions" appears as expected.
/*! nontype template function that just returns the template value.
\tparam @c size is a constant integer argument.
\returns Constant integer size always.
\pre No preconditions.
\post No side effects.
\throws Nothrow so never.
int i = non_type<9>();
assert(i == 9);
template <int size>
But I find that this isn't so for struct and class,
\pre \post \return are not passed through to the final html.
Here is a typical actual example of a class with template parameters for which there are some
\tparam Min The minimum integer value that this type may hold (as a integer literal < Max).
\tparam Max The maximum integer value that this type may hold (as a integer literal > Min).
\pre Min < Max.
class safe_signed_range :
Min < Max,
"Minimum must be less than maximum."
Obviously, the restrictions on the template parameters are not exactly 'preconditions', nor is the
result of a MPL compile-time computation using a struct or class really a 'return' (and
Postcondition and throws are even less meaningful).
But I'm sure I'm not the only one to expect this to work.
It is possible to use
\remark Precondition: Min < Max.
\tparam (see above \tparam Min .)
to provide this information that is needed by the user.
So should I try to alter docbook2boostbook to allow \pre, \post and \return to output for
class/struct as with functions,
or just declare it a feature and use the other ways as above?
--- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow_at_[hidden]
This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC