[Bf-committers] Re: Code documentation

[Ton Roosendaal]

Hi,

> Also, are there any requests for what to doxygenate
> first?  What areas of code are the most used and/or
> would benefit the most from extra comments?

The code has been structured in quite a weird way, especially because  
of historic reasons.

- it started in fact with blender/src and blender/include (+imbuf, glut)
here is were almost ALL blender code resided in the past. mostly  
written by me, zr, frank and later on reevan. All c code.

- then the game engine was added in a new directory, with a structure  
designed by erwin. Code is there from a lot of NaN developers, all in  
c++

- then nzc (and a bit zr) started reorganizing the old blender/src  
stuff, and put that in loads of smaller .h files, and several modules  
(blenlib, blenkernel, blenloader, etc)

- the internal render system was fully reorganized and improved as well  
(nzc). But now 2 renderers reside together, with quite some double code  
as well.

- file reading/writing was complexified quite some for the 3d web  
plugin and publisher features (hans, frank). What of this should remain  
there?

- replacing glut with the much better ghost (maarten, zr) was not  
finished either, the low level blender interface code (screen.c,  
mywindow.c) was never really cleaned up for it.

- the python API was rewritten a couple of times, and is quite a  
chaos...

Due to time (deadline!) constraints, that all was still pending. So the  
directory and module structure is quite obscure, not really providing  
additional info how blender works, or how to locate the parts you  
should code in when you want to work.
After doing the translation work (in the c code parts) it was confirmed  
again that there's still not a coherent vision on how it should be  
organized. Or better said; the current organisation assumes a higher  
level that is not really there, because of too many internal spaghetti  
dependencies. And last but not least, there are quite some nasty  
patches in the (old) code that seem to work, but that shouldn't be  
there...

Now for your work: the added value of doxygen really should be giving  
insight in the structure... especially how function calls (and files)  
relate. We should find a way that you don't work on parts that are due  
to change, or are in fact patches, or that don't even work! And how are  
you going to find out the difference?

There are quite some 'safe' parts where you could start however. Let's  
evaluate input from people here, and check with me the feasibility of  
doxygenizing that part. It might be well possible that some docs just  
have to be provided by me, because it would be cruel to expect someone  
to reverse egineer all of that.

Safe parts that can be done according to me:
- ghost
- (in fact all libraries in intern)
- imbuf
- radiosity
- blenkernel
- render

Stay away from:
- blender/src/  (well, individual files maybe)
- bpython (subject to rewritten)
- deflate, encrypt, decrypt, streamglue, sign (might be removed)
- makesdna (h files are interesting, but genfile.c is nasty)

Maybe:
- blenloader
- blenlib
- game engine dir ? (I don't know that code well, I get mixed reactions  
about it...)
- img (is not realy used a lot)

-Ton-

------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton@blender.org