Re: [Boost-users] [boost-users][parameter] ArgumentPack Documentation Best Practices

Subject: Re: [Boost-users] [boost-users][parameter] ArgumentPack Documentation Best Practices
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-04-11 07:49:47

> -----Original Message-----
> From: boost-users-bounces_at_[hidden] [mailto:boost-users-
> bounces_at_[hidden]] On Behalf Of Christoph Heindl
> Sent: Monday, April 11, 2011 12:12 PM
> To: boost-users_at_[hidden]
> Subject: [Boost-users] [boost-users][parameter] ArgumentPack Documentation
> Best Practices
> 
> Hi,
> 
> I wonder if anyone could share his best practices as far as documenting
> Boost.Parameter enabled constructors is concerned.
> I'm currently doing something along the lines of
> 
> /** Construct from named parameters and use defaults where parameters are
> empty
> *
> *
> * \tparam Opts ArgumentPack of options. The following options are
supported
> *  - \a min_group_size minimum number of supporting correspondences to
form
> a group.
> *  - \a ntrials number of times to form basis from two randomly selected
> correspondences.
> *  - \a bin_size_pos quantization size for transformed point coordinates.
> *  - \a bin_size_orientation quantization in radians for surface
orientation
> angles.
> *
> */
> template<class Opts>
> group_geo_hash(const Opts &opts)
> {
> 	this->init(
> 	  opts[Keywords::_min_group_size | 10],
> 	  opts[Keywords::_bin_size_pos | LibFundament::rasFloat(10)],
> 	  opts[Keywords::_orientation_rad | LibFundament::rasFloat(0.2)],
> 	  opts[Keywords::_ntrials | 0]);
> 	}
> }
> 
> which is sub-optimal, because default values for options and option types
are
> missing. Doxygen can deduce types for regular parameters as well as
default
> values. Ideally this should work for boost.parameters as well :) Even
better,
> Doxygen could warn about undocumented parameters.

I've used Doxygen tags WARN_IF_UNDOCMENTED and  WARN_IF_DOC ERROR, and
WARN_NO_PARAMDOC
both in my doxyfile and in jamfiles - all =YES, sending the output to a
named WARN_FILE = Boost_options_warnings.txt.

This gives you a list of missing C++ Doxygen comments doc items  if you are
using Doxywizard (recommended at first because it is *much* quicker than
running Quickbook toolchain).

If the warnings file is empty, it is worth running the full docs :-)

HTH - though I'm not sure it solves your real problem.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]