[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. Any thoughts? Best regards, Christoph
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of Christoph Heindl Sent: Monday, April 11, 2011 12:12 PM To: boost-users@lists.boost.org 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 +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On Mon, Apr 11, 2011 at 1:49 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
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.
Paul, thanks for your feedback, but I doubt that it solves my problem, since my undocumented parameters are actually boost.parameter keywords nested inside an argument pack structure (see my initial posting). Best regards, Christoph
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of Christoph Heindl Sent: Monday, April 11, 2011 1:11 PM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [boost-users][parameter] ArgumentPack Documentation Best Practices
On Mon, Apr 11, 2011 at 1:49 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
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.
thanks for your feedback, but I doubt that it solves my problem, since my undocumented parameters are actually boost.parameter keywords nested inside an argument pack structure (see my initial posting).
I feared not ;-) Paul
participants (2)
-
Christoph Heindl -
Paul A. Bristow