Re: [Doxygen-users] Documenting C structs

[Clayton C. <crc...@cs...>]

	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."