[Boost-docs] Using Doxygen comments to specify conditions on template parameters of a class or struct

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.
 
       @b Example:
      \code
      int i = non_type<9>();
      assert(i == 9);
      \endcode
 
  */
  template <int size>
  int nontype()
  {
    return 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
requirements:
 
/*!
\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.
*/
 
template<
    boost::intmax_t Min,
    boost::intmax_t Max
> 
class safe_signed_range :
        safe_signed_range<Min, Max>
  >
{
    BOOST_STATIC_ASSERT_MSG(
        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.
 
or
 
\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
 
---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]