Re: [Boost-docs] Coding round Microsoft warning C4100 prevents Doxygen documenting the parameter with \param

Subject: Re: [Boost-docs] Coding round Microsoft warning C4100 prevents Doxygen documenting the parameter with \param
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2011-09-06 16:32:04


Le 06/09/11 17:19, Paul A. Bristow a écrit :
> I have just encountered an annoying side effect of coding round the almost entirely unhelpful
> Microsoft warning
>
> C4100 unreferenced formal parameter.
>
> The unreferenced parameter is placed in C comments like /* my_unreferenced_variable */ to 'code
> round'.
>
> The unwanted effect is that a Doxygen \param trying to document the parameter gives a message, for
> example
>
> warning: argument 'current_valid_value' of command @param is not found in the argument list ...
>
> So the parameter name *is* useful, even if not referenced (here).
>
> For example:
>
> /*!
> \brief Compute an operation on the checksum with the current valid value.
> \post Do nothing. The checksum is unchanged.
>
> \param current_valid_value is the current valid value analysed.
> \param valid_value_counter is the number of valid value(s) already counted (the current value is
> not included).\n This is also the position (above the valid values) of the current value analysed (0
> <= valid_value_counter< n).
> \param checksum is the current checksum.
>
> \remarks This function should be overloaded if you want to calculate the checksum of a sequence.
> */
> static void operate_on_valid_value( const int /* current_valid_value */, const unsigned int /*
> valid_value_counter */, int&checksum )
> {
> }
>
> And the parameters current_valid_value and valid_value_counter are not documented :-(
I don't know if separating the declaration from the implementation works?

   inline static void operate_on_valid_value( const int current_valid_value, const unsigned int
valid_value_counter, int&checksum );

   static void operate_on_valid_value( const int /* current_valid_value */, const unsigned int /*
valid_value_counter */, int&checksum )

   {
   }

> I therefore propose to recommend instead
>
> in https://svn.boost.org/trac/boost/wiki/Guidelines/WarningsGuidelines
>
> that *all* jamfiles contain code to *suppress this warning*, rather than bothering to 'code round
> it', for example with
>
> requirements
>
> <toolset>msvc:<cxxflags>/wd4100 # unreferenced formal parameter.
>
> Effectively this means that Boost considers the warning to be worth ignoring :-)
>
> Any dissenting views?
>
>
Generating documentation from the source code has always a lot of
secondary effects. As far as it is possible I will prefer to preserve
the possibility to catch the warnings. If the previous suggestion works,
it could be added to the guidelines to preserv warning reporting and a
good documentation.

Best,
Vicente


This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC