[Bf-committers] Doxygen docs?

[Jean-Luc Peuriere]

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