[Bf-committers] doxygen updates

[Ton Roosendaal]

Hi Alex,

There's a gap between "what we want" and "what works for us". I'm  
afraid the doxy project is too much wishful thinking here. Apart from  
some energy Casey put in it in the past, none of the developers here  
seems to actively support it.

I also think it is dangerous to do code documenting without fully  
understanding the structure and actual implementation. Code documenting  
also should not just replace what you can find out already by reading  
code itself. What we clearly miss most is good documentation providing  
general overview, like how the code (c & h files, APIs) relates in  
Blender.

The major problem is - of course - that the current code structure  
doesn't document well at all, most of it is just an inheritence from a  
dark past that has been 'reorganized' a couple of times based on quite  
individual (and sometimes conflicting) visions.

If you are motivated helping out with technical documentation for  
Blender, we might better define targets that help the current projects  
better. Like managing and upgrading the current documentation on  
blender.org. And/or revising what is still available from the NaN tech  
docs, and reconstruct/edit that based on what is still valid.
Or building an overview of all current python scripts... or creating  
documentation for users (tutos/demos) when we do releases. Just to  
mention a few things.

Most important is to find out what your personal incentive is. What is  
it you like to do, and what is your competence or background?

-Ton-


On Friday, Jan 2, 2004, at 03:25 Europe/Amsterdam, Alex Combas wrote:

>
> Id like to start updating the blender source so that
> it
>  will render nicely with doxygen and I just have a few
>  questions.
>
> Is anyone currently in charge of documentation?
>
> FYI:
>
> The current blender cvs tree already has a couple of
> doxygen files in it such as:
>
> /blender/doc/doxygen.main
> /blender/doc/Doxyfile
>
> It appears that someone put a lot of effort into these
>
> files as they sill work very well! However it seems
> that they are getting out of date since the version
> numbers havent been updated since Blender-2.27
>
>
> Ive been looking at a lot of blender source comments
>  lately and it looks like it would be quite easy to
> modify them so that they render properly in doxygen!
>
>
> Here is an example of a file that already works
> properly with doxy:
> /blender/source/blender/readblenfile/intern/BLO_readblenfile.c
>
> way to go sirdude! :)
>
> Although I recommend that coders wishing to update
> their own files have a look at the doxygen user manual
> since it gives more straitforward examples.
>
>
> AFTER all the current comments in the blender code
> have been updated to work with doxy, then Id like to
> start documenting the rest of the code as well but
> that task is rather daunting!
>
>
>
>
> __________________________________
> Do you Yahoo!?
> Free Pop-Up Blocker - Get it now
> http://companion.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  
http://www.blender.org