[Bf-committers] Doxygen docs?

[joeedh]

joeedh wrote:

> Alexander Ewering wrote:
>
>> On Wed, 5 Jan 2005, joeedh wrote:
>>
>>> Hi, I'd be interesting in writing code comments for parts of 
>>> Blender's source code.  I have a fairly good understanding of it, 
>>> and whoever was previously doing this seems to have given up.  I've 
>>> gotten Doxygen to work, and I've found the main doxygen 
>>> configuration/source files in doc/.
>>
>>
>>
>> For me (and probably for any other serious developer), the code is 
>> pretty
>> much self-explanatory... better spend the time on coding ;)
>
>
> The code is self-explanatory, after you finish having apoplexy at the 
> wierdness of it :)  .  Blender violates so many software-design 
> "rules" that it isn't even funny.  Also there is a contradiction 
> between the design and the code: The design in abstracted, but the 
> code is not (referring to the main code in blender/source/blender of 
> course).  I'm excluding the sound and image modules BTW, I've never 
> looked closely at them but they're in C++ and they seem to be fine.
>
> Documentation would really help.  I figured out the sourcecode on my 
> own, but it sure would've helped to have nice code documentation.   
> Also with good documentation C amateur's could more easily help code 
> things (oh!  The horror!).  This is, after all, an open-source project.
>
> joeedh
> _______________________________________________

(WARNING: mini-essay follows)

Here is a small ten-minute essay dedicated to why documentation would 
help.  (BTW it's bad because I did in ten minutes, I'm tired and it's 
raining *shiver* I hate rain).

Blender is divided into basically four sections:  what I call Direct 
Code, Internal Libraries, External Libraries, and the gameengine.

Internal Libraries and the gameengine arn't too bad.  A lot of the code 
in there has been rewritten in C++ (the gameengine was written *in* C++) 
and the best of it (like GHOST) even has doxygen comments.

However, the bulk of Blender's code  (in terms of features) is what I 
call Direct Code, located in source/blender (except for the main() 
function which is in creator/creator.c).  Except for the sound, image, 
and boolean modules, almost every feature there is coded in C.

There are many problems with this code.  First of all, there is this 
habit to do copy-paste struct inheritance (which certainly confused me 
at first).  For example, with the exception of Library block structs, 
each structure has a "struct <structname> *next, *prev" at it's head 
instead of a "Link head" (like it should be).

Also, there is a lack of abstraction within the C code, even though the 
design is fairly abstracted.  For example, adding a new object type, or 
a new Library block type, requires adding code to about ten different 
files, as everything is done on a per-case basis.  I understand why this 
is; after all a lot of that code comes from a time long before modern 
software design.  But it's still confusing. 

And don't forget the spacetypes.  When I made an abstracted spacetype 
layer (which I did in C) for C++ components I have to add code in three 
seperate source files.  Finding where to put the header drawing code was 
especially annoying.

Blender is a great application, I know, and the code works, but let's 
face it: good documentation would be really helpful to navigate through 
its wierdness!

joeedh