[Bf-committers] Example documentation

[Laurence Bourn]

Seems to be an excellent start.

After all you have know what's there before you start refactoring. For me
the biggest problem with the code is not the structure more that it's so
very hard to understand what things do. One method is to give up
understanding untill a new structure magically appears OR use such a
documentation system to increase global understanding of the code. Moreover,
it's something that can be done! It is possible to take the time to study a
piece of code in blender and work out what it does and it's
responsibilities, (I guess some people are already making good progress in
this), what a shame if that knowledge is not expressed in documentation!
Having all the knowledge in a couple of people's headz is no good. <*waves
to daniel*>

This is definately a positive step forward.

It would be great to keep a current Doxygen output on the web. Imagine if
blender had such excellent documentation as QT (which I constantly refer to)
http://doc.trolltech.com/3.0/ Like that stuff is just empowering man...

Cheers,
Laurence. 

-----Original Message-----
From: Ton Roosendaal [mailto:ton@blender.org]
Sent: 25 April 2003 13:34
To: bf-committers@blender.org
Subject: Re: [Bf-committers] Example documentation


Hi,

Interesting result... but this is "documenting" at the lowest level,  
meaning adding comments to the code itself. That's essential too,  
although it assumes the code itself being structured well!

The main issue to discuss then, is what people think of adding a tool  
(doxygen) to interpret c files. Opinions please!

-Ton-




On Friday, Apr 25, 2003, at 02:48 Europe/Amsterdam, Casey Corn wrote:

> Hi all!
>
> As promised, here is an example of the doxygen system,
> and the methods I propose to use.
>
> I looked into the way GHOST was documented (thank you
> Laurence Bourn :) and I tried to pattern what I did
> off of that.  Since GHOST is mostly c++, I made some
> changes here and there.
>
> I created a directory called "doxygen" in the
> bf-blender directory (same level as blender, libs, and
> old directories) and put the doxygen config file in
> here (this file could also go in the blender/doc
> directory).  This is also where doxygen creates the
> html directory and files.  The config file I used is:
>
> http://stu.aii.edu/~cmc271/blender/doxygen/Doxyfile
>
> The GHOST project uses a file called ghost_doxygen.in,
> presumably to customize the Doxyfile configuration
> file to enable certain doxygen features.  We may want
> to look into doing the same thing.
>
> I documented the file source/creator/creator.c since I
> had already studied it and new mostly what was
> happening.  The commented file is:
>
> http://stu.aii.edu/~cmc271/blender/creator.c
>
> After running "doxygen" in the doxygen directory, the
> output is placed in an appropriate directory: html for
> html docs, latex for latex docs, rtf for rtf docs,
> well you get the idea :).  The output generated is:
>
> http://stu.aii.edu/~cmc271/blender/doxygen/html/
>
> Please let me know what you think!
> Thanks,
> Casey
>
> __________________________________________________
> Do you Yahoo!?
> The New Yahoo! Search - Faster. Easier. Bingo
> http://search.yahoo.com
> _______________________________________________
> Bf-committers mailing list
> Bf-committers@blender.org
> http://www.blender.org/mailman/listinfo/bf-committers
>
>
------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton@blender.org

_______________________________________________
Bf-committers mailing list
Bf-committers@blender.org
http://www.blender.org/mailman/listinfo/bf-committers