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