[Bf-committers] Doxygen docs?

[Martin Poirier]

I'll agree with Jean-Luc here. What's important in
comments/docs isn't so much What the code does (this
usually fits in one or two lines) but rather How it
does it and Why it does it this way (what are the
limits/advantages). More often than not when looking
at unkown code, that is the true question.

On the point of doing that as docs outside of code, I
disagree. While standalone docs are important and
shouldn't be left out of the equation, it's usually
more convenient to have the docs right in the code
where you need it. Otherwise, you always end up
jumping between the code base and the documentations.

I don't know doxygen enough to have a definite opinion
on its use in particular though.

Martin

--- Jean-Luc Peuriere <jlp at nerim.net> wrote:

> 
> Le 5 janv. 05, à 23:29, joeedh a écrit :
> 
> > I meant detailed doxygen comments.  Of course I
> add comments to my 
> > code!  And I'd add doxygen comments, too, (excuse
> the "!" up there) 
> > except that I guess not everyone likes that.  And
> anyway in the case 
> > of Blender it makes sense to just use the .h files
> 
> Documentation is useful and lacks a lot in blender.
> Architecture 
> document is not enough, true.
> Blender is a bit too big morsel to eat without it.
> 
> But I find Doxygen style documentation generally
> worse than useless in 
> procedural or abstract types code.
> 
> Most of them are paraphrase of the code, where a
> true doc should 
> present the algorithm and the boundaries
> conditions, instead of stating that  the var
> NumberOfVertexCounter is 
> indeed the counter of the number
> of vertex.
> 
> What need to be documented in this case is the
> structs and how the API 
> manipulates them.
> Which means not documenting each function but the
> relationships.
> 
> Much better Imho to do a clear document outside of
> code files. And the 
> best way is often nice graphs.
> 
> For OOP code, the classes structure things is such
> ways that this kind 
> of documentation is more suitable.
> But again, beware of not paraphrasing the code.
> 
> -- 
> Jean-Luc
> 
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at projects.blender.org
>
http://projects.blender.org/mailman/listinfo/bf-committers
> 



		
__________________________________ 
Do you Yahoo!? 
Take Yahoo! Mail with you! Get it on your mobile phone. 
http://mobile.yahoo.com/maildemo