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