RE: [Doxygen-users] Comments duplicated in header and source files

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

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


=20


________________________________

	From: dox...@li...
[mailto:dox...@li...] On Behalf Of
Ken...@mt...
	Sent: Friday, March 03, 2006 09:14
	To: dox...@li...
	Subject: [Doxygen-users] Comments duplicated in header and
source files
=09
=09

	I am just learning about Doxygen and have a basic question
regarding comments.  Must we cut and paste (manually) the comments in
the source to the header file?  For example, you may have a C function
with a comment/description and parameter explanations and so on.  You
want to keep the information in the source code, but you also want it
echoed in the header file.  How do we do this easily and how do we
ensure they match?  If one is out of sync, we have problems. =20

	Regards,=20

	Kenny=20