doxygen-users

RE: [Doxygen-users] Documenting C structs

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

given that the differences between struct and class is minimal, what's wronw
with the way it documents them now?

-----Original Message-----
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.

--pc

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

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

Re: [Doxygen-users] Documenting C structs

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

	Well, you obviously know the language(s) better than I, but I
was thinking that Doxygen should provide the user with the flexibily
and freedom to document just and only what they want to document, and
that it should also give them a certain (reasonable) amount of freedom
to do so in whichever way that they see fit.

	Now, I've made the above assertion based upon what I already
know about the system: Doxygen lets the coder use the Qt or Javadoc
syntax; it lets the coder document function arguments beforehand or
inline; and it lets the coder document the code in a file or files
that're completely divorced from the code.  These points alone show
that the system is already trying to be rather flexible, and -- it
seems to me -- that this @member (or whatever) wouldn't be too bad of
thing to add in the name of flexibilty.  (Of course, the fact that it
seems I'm the only one to have asked or to be asking for this kind of
thing certainly goes wuite a way in arguing against me, eh?)

	Granted, the situation could get rather hairy when function
pointers or member functions are encoutered, but I seem to think that
those are substantial enough members to to make documenting then
within the struct/class, as opposed to beforehand, quite feasible.

	I'm sorry if I sound beligerent.  I really do like Doxygen and
I'm very appreciative of the work that's already been put into it.

--c



On Wed, Jul 25, 2001 at 10:37:26AM -0400, Wagner, Victor wrote:
> 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.
> 
> 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.
> 
> 
> 
> On Tue, Jul 24, 2001 at 06:57:21PM -0400, Wagner, Victor wrote:
> wronw
> 

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

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