[Bf-committers] Doxygen docs?

[Ton Roosendaal]

Hi,

I completely agree with Jean-Luc here. The previous attempt to doxify  
the code didn't reveil any structure nor insight in the code, and  
instead just rewrote *very* readable parts of code in commented text.  
Doing that in our current C code just makes it completely unworkable,  
with as only benefit you can use a Doxy tool (who uses that?) to go  
over code.

Since C++ "architecture" design can become extremely complex and  
abstractly warped, usage of Doxy tools and class-browsers or high level  
tools as CASE/Rational Rose seem to be a standard for such work. But I  
think that only really works when you do that consistantly from  
scratch. Applying these kind of tools - or the "engineering" habits you  
learned on uni - on Blender will just fail. As I've clearly witnessed  
in the NaN days.

There are many good ways to develop software, I won't dispute nor want  
to discuss whether "modern" software engineering methods are good or  
bad. We can simply agree on the fact that hasn't been applied on  
Blender. Not on its old C code, but apparantly also not on the so much  
praised Ghost, Soundsystem, Solid or the Game engine. These are typical  
engineer level designed code products, and at least as hard to  
understand or maintain as any ugly non-engineered part of Blender in C.  
Hardly anyone maintains this beautiful documented C++, and oh yes, it's  
buggy as any other part of Blender. Too often "beautiful architecture"  
gets  confused with proper working software.

So, for me there's only thing that counts, and that is a devoted &  
competent person or team who decides to spend time on it, and maintain  
and improve it.

As I said in the previous discussion on Doxygen too; it useless to work  
on code docs from a bottom-up approach; mostly because the low level  
code has too many polluted inconsistancies. We first need top-down  
level docs, describing how it was *supposed* to work, describing what  
you can do to improve it, and hopefully resulting in better modular  
structure with documented APIs.

For example; I've worked on cleaning up render code - which was (still  
is) highly chaotically linked and reused and abused all over Blender.  
Documenting the mess how it worked before would have been a total waste  
of time, since it works already much different now. With the work I did  
we're heading to a much simpler and understandable render module, which  
then can *finally* get a clear and understandable API and internal  
structure doc.

Sometimes docs come after you do code work, especially when its about  
old stuff like Blender. If anyone here likes to work on improving  
Blender parts, I hope that can fit within such an approach too. Trying  
to grasp how it should/could work, then cleanup/implement and document  
that.

-Ton-



On 6 Jan, 2005, at 0:37, Jean-Luc Peuriere 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
>
>
------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton at blender.org  
http://www.blender.org