Re: [Doxygen-users] Question on function-parameters documentation..

[Dimitri v. H. <di...@st...>]

On Sun, Dec 30, 2001 at 08:43:21PM +0100, Jaap Suter wrote:
> Hello,
> 
> I'm new on the list and I've only been working with Doxygen for four days 
> now. I've searched the documentation and the online mail-archives but 
> coulnd't find any help on this one...
> 
> What is the difference between:
> 
> /*!
>      \brief Some function
>      \param x Argument X
> */
> void Function( x ) {}
> 
> and
> 
> /*!
>      \brief Some function
> */
> void Function(
>                x //!< Argument X
>              )
> {}
> 
> Basically, what is the difference between documenting the parameter in the 
> source-comment, or directly after the declaration of the argument?

There should be no difference in the output (if there is, please send
a bug report). It is just a matter of taste how you comment the input. 
Both styles have their pros and cons.

> I'd rather use the latter, cause it saves me typing the argument-name twice. 
> However, when I use it all sorts of things dissappear in my generated 
> documentation.
> 
> With the functions that use the \param method I get the brief comment below 
> it with a 'more...' behind it. With the other method I don't get that. And 
> also the detailed information just seems to be ignored with the latter 
> method. Very confusing.

The confusion is caused by Function not being a real prototype. If you use

/*!
     \brief Some function
*/
void Function( 
               int x //<! Argument x
             )
{
}

then the result should be the same for both cases. Note the "int".

Regards,
  Dimitri