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

[Glenn M. <gle...@vo...>]

Although I can certainly see the merits of not having to type the
argument name twice, you will be better off in the long run if you do
put it into a comment block.

I haven't fully played with the inline comments. What little I have done
brought to light an interesting facet. Doxygen does not group the inline
comments into a comment block. Specifically, when I used the //! style
for the headings of my files, Doxygen starting pulling off comments from
the file heading and putting them on the first valid code item it found,
such as a #define. I now have input filters that turn all //! comments
into /** ...**/ comment blocks before piping it through Doxygen.

In your case, if the description to a parameter went more than one line
(which could happen at my company where the developers are restricted in
line lengths), your parameter comment could get split up and associated
with incorrect elements.

Another aspect to consider that only a tech writer like me would care
about, the second option doesn't give a lot of consistency in the
output, particularly when you start adding more than the @brief
description, such as @return, @retval, @bug, @ingroup, and a detailed
description.

I created templates that I placed in the code (or the developer used)
that specifies the order in which information is displayed.

/** @brief _TBD_
 **=20
 ** @param _TBD_
 ** @param _TBD_
 **
 ** @return _TBD_
 **
 ** _TBD_ [Detailed Description]
 **
 ** @bug None.
 ** @ingroup _TBD_
 **/

I would fill in as much of the _TBD_ stuff as I could. Anything I didn't
know, I left for the developers to flesh out.

My template design purposely places the @param and @return/@retval in
between the @brief and the detailed description. It provides a much more
usable output, because then the syntax is only separated from the @param
by a @brief statement and not some long detailed description. Also, our
developers made a strong case that all of these items should be present
in the template with a "None" if it didn't apply; that way, they
wouldn't forget it. (I have an input filter that turns @bug into @lim
for a user-defined "Limitations and Caveats" that does often get filled
in.)

Using a comment block provides another advantage in that 95% of the
information that would need to be extracted could be found there. This
meant that the developers could add all sorts of normal // comments
anywhere in their code to clarify things that only they would care about
in the implementation.=20

HTH,
Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
gle...@vo...



> -----Original Message-----
> From: Jaap Suter [mailto:s98...@ho...]
> Sent: Sunday, December 30, 2001 12:43 PM
> To: dox...@li...
> Subject: [Doxygen-users] Question on function-parameters=20
> documentation..
>=20
>=20
> Hello,
>=20
> I'm new on the list and I've only been working with Doxygen=20
> for four days=20
> now. I've searched the documentation and the online mail-archives but=20
> coulnd't find any help on this one...
>=20
> What is the difference between:
>=20
> /*!
>      \brief Some function
>      \param x Argument X
> */
> void Function( x ) {}
>=20
> and
>=20
> /*!
>      \brief Some function
> */
> void Function(
>                x //!< Argument X
>              )
> {}
>=20
> Basically, what is the difference between documenting the=20
> parameter in the=20
> source-comment, or directly after the declaration of the argument?
> I'd rather use the latter, cause it saves me typing the=20
> argument-name twice.=20
> However, when I use it all sorts of things dissappear in my generated=20
> documentation.
>=20
> With the functions that use the \param method I get the brief=20
> comment below=20
> it with a 'more...' behind it. With the other method I don't=20
> get that. And=20
> also the detailed information just seems to be ignored with=20
> the latter=20
> method. Very confusing.
>=20
> I could provide you with a short example should that be neccesary.
>=20
> Thanks for your help,
>=20
> Jaap Suter
>=20
>=20
> _________________________________________________________________
> Chat on line met vrienden en probeer MSN Messenger uit:=20
> http://messenger.msn.nl
>=20
>=20
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>=20