[Bf-committers] Doxygen docs?
Jean-Luc Peuriere
jlp at nerim.net
Thu Jan 6 00:37:43 CET 2005
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
More information about the Bf-committers
mailing list