RE: [Doxygen-users] Comments in C files and H file

[Randall, L. <l-r...@ti...>]

On Tue, Mar 14, 2006 at 06:43:04PM -0500, Nick MacDonald wrote:

> I assume, in this case, that you want to document the C code for
designers but document the header files for customers/end users. In
this case I can't see any way around having two sets of documentation.

Here are two approaches.  As you can see from my reply to Dimitri, the
bottom one is what we use to control exactly what you discuss.  The
"@fn" line in the source file can be commented out for projects that do
not pull documentation from the header.
=20
Two sets of header files are a file maintenance nightmare.



Regards,
Larry Randall=20

________________________________

From: Randall, Larry=20
Sent: Tuesday, March 14, 2006 13:04
To: 'di...@st...'
Cc: Ken...@mt...; dox...@li...
Subject: RE: [Doxygen-users] Comments duplicated in header and source
files

	We have a somewhat unique requirement, in that some (header
file) function documentation is only for internal use on some projects.
On other projects, the same header file documentation may be released to
the customer.
	The rules allow us to control "what goes where" simply by
manipulating the C file for the project.


	Regards,
	Larry Randall=20
=09
________________________________

	From: Dimitri van Heesch [mailto:do...@gm...]=20
	Sent: Monday, March 13, 2006 07:36
	To: Randall, Larry
	Cc: Ken...@mt...; dox...@li...
	Subject: Re: [Doxygen-users] Comments duplicated in header and
source files
=09

=09

		These rules look rather complex to me.
		Here are my rules:
		- Use only one comment block per function
declaration/definition pair
		  (you can also put the brief description at the
declaration and the
		   detailed description at the definition, but this
requires some more discipline from your users). It's better to put all
comments in either the header file or the source file.=20
		- Avoid the use of @fn (unless you must put the comment
block in a separate file).
		- Document the header file (with @file).
		- Optionally document the source file (with @file): in
this case doxygen will copy the comment block for a function to both
files for you (so from declaration to definition and visa-versa).=20
		- Never copy & paste comment blocks when dealing with
the same function (this should not be needed!)
	=09
		Regards,
		  Dimitri
	=09
	=09
		On 3/3/06, Randall, Larry <l-r...@ti...> wrote:=20

			Documentation Source Rules

			These rules apply to the C source file.

			n        If "@fn" precedes the function name,
AND the header file contains proper documentation for the function, the
description for both the source file and the header file will always be
taken from the header file, and the source file description will be
ignored.

			u       EXCEPTION:  If implementation variables
inside the function  use a Documentation Comment opening ("/**") in the
C file, they will appear in both the source file and the header file
documentation.

			l        If "@param" is used, the heading
"Parameters:" will precede the description, but the heading and
description will not be collocated with the other parameters.

			l        Normally, these local variables should
not appear in the documentation.

			u       Standard comments ("/*") will not appear
in documentation.

			n        If "@fn" precedes the function name,
AND the header file does not contain proper documentation for the
function, OR the documentation in the header file does not begin with
"/** ", no documentation will be output.  This is true even if the
source file contains documentation.

			n        If "@fn" does NOT precede the function
name, AND the header file contains proper documentation for the
function, the description for both the source file and the header file
will always be taken from the source file, and the header file
description will be ignored.

			u       EXCEPTION:  If implementation variables
inside the function  use a Documentation Comment opening ("/**") in the
C file, they will appear in both the source file and the header file
documentation.

			l        If "@param" is used, the heading
"Parameters:" will precede the description, but the heading and
description will not be collocated with the other parameters.

			l        Normally, these local variables should
not appear in the documentation.

			u       Standard comments ("/*") will not appear
in documentation.

			=20


			Regards,
			Larry Randall=20
		=09

			=20