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

Subject: [Boost-docs] Coding round Microsoft warning C4100 prevents Doxygen documenting the parameter with \param
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-09-06 15:19:36

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 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?

Paul

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