RE: [Doxygen-users] Documenting C structs

[Wagner, V. <VW...@se...>]

Shall we also, then, ask that local, namespace, and global variables be
documented in the same fashion?
If so, what about variables declared "way down" in the middle of the code?

Please note I'm not advocating this (yet), I'm just trying to get the entire
story.

-----Original Message-----
From: Clayton Carter [mailto:crc...@cs...]
Sent: Wednesday, 2001 July 25 10:19
To: dox...@li...
Subject: Re: [Doxygen-users] Documenting C structs


	Because I'd like to have the flexibility of being able to
document the structs/unions/classes the same way that functions are
documented.  It's possible to document functions beforehand (ie - with
@param) or inline (ie - with the /*!< notation) and I think it'd be
handy to have the same for structs/classes.  By documenting the
(whatever) beforehand (but, of course, keeping that documentation
close at hand), you can keep the (whatever) declaration simple and
concise.  For instance

	...
	* @member min blah blah min blah
	* @member max blah max blah blah
	...
	...
	double min, max;
	...

	instead of something like:

	...
	double min;   /*!< blah blah min blah, possibly
		       *   stretching over
		       *   multiple lines, right? */
	/*! blah max blah blah */
	double max;
	...

	of course, any not-insane person would try to use a consistent
method over both definitions, but I still think that the former is
more elegant and readable.

--c


On Tue, Jul 24, 2001 at 06:57:21PM -0400, Wagner, Victor wrote:
> given that the differences between struct and class is minimal, what's
wronw
> with the way it documents them now?
> 
> From: Clayton Carter [mailto:crc...@cs...]
> Sent: Tuesday, 2001 July 24 17:36
> To: dox...@li...
> Subject: [Doxygen-users] Documenting C structs
> 
> 
> 	What have folks found to be the best way of documenting C
> structs?  I was hoping that there'd be a command `@member' so that
> structs could be documented like functions.  For instance, we've got
> this:
> 
> /**
>  * Function to init some data
>  * @param inFile ...
>  * @return ...
>  */
> int init_data( char *inFile )
> 
> 	and we can also use the `/*!<' syntax to document `inFile'
> right where we define it.  Anyway, it seems as this on location
> documentation is only option when working with structs.  I'd like
> something like this:
> 
> /**
>  * @struct data
>  * @brief ...
>  * @member mins ...
>  * @member maxs ...
>  * @member means ...
>  * etc.
>  */
> 
> typedef struct {
>   double mins, maxs, means, medians, sigs, totals;
> } data;
> 
> 
> 	Please chastise me if I'm way off base here.  I've scanned the
> docs, but not seen anything like what [I think] I'm talking about.
> Thanks.
> 
> 

-- 
Clayton Carter   crc...@cs...
"My mom says I'm the handsomest guy in school."

_______________________________________________
Doxygen-users mailing list
Dox...@li...
http://lists.sourceforge.net/lists/listinfo/doxygen-users


This transmission may contain information that is privileged, confidential
and exempt from disclosure under applicable law.
If you are not the intended recipient, you are hereby notified that any
disclosure, copying, distribution, or use of the information contained
herein (including any reliance thereon) is STRICTLY PROHIBITED.
If you received this transmission in error, please immediately contact the
sender and destroy the material in its entirety, whether in electronic or
hard copy format.
Thank you