[Bf-committers] doxygen updates

Casey Corn bf-committers@blender.org
Fri, 2 Jan 2004 11:25:46 -0800 (PST)


Hello,

--- 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?

I guess that if anyone fit that description it would be me.  Really, I'm just
the one who has done a little bit of work on it and started working out a set
of guidelines.  Unfortunately, I'm not an expert programmer or very good at
getting doxygen to do what I want (yet).

> 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

Yes.  I appear to be one of a very few who are interested in putting documents
into the code, and I have been extremely busy the past several months.  As much
as I'd like it to be otherwise, blender has been put onto the back burner for a
while.  It looks as if I will be having a bit more free time in the near
future, so this might change. 

> 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! :)

Yes, there appears to be quite a few files and groups of files that have good
documentation.  In particular, lot of the stuff in blender/intern has doxygen
style comments.  The ghost module especially has been pointed out as a good
example of how to document with doxygen.

> 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.

I agree.

> 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!

I hope that you will be able to do this better than I have been. :/

Ton provided a bit of the blender source history, and has suggested which
modules to document first in this e-mail:

http://www.blender.org/pipermail/bf-committers/2003-April/002488.html

People have also expressed interest in getting the GUI documented, but this was
before the huge update that was made to this area.  I don't know how things
stand now.  Also, documenting flags and #defines in editmesh.c has been
mentioned here (item #5):

http://www.blender.org/pipermail/bf-committers/2003-December/004940.html

I've done a bit in the imbuf interface, but it hasn't been committed yet.  I'm
still struggling with getting what I want out of doxygen.

For a look at some discussion and a few guidelines, the thread started with
this e-mail might be instructive (click "Next message" link to follow the
thread):

http://www.blender.org/pipermail/bf-committers/2003-June/003252.html

Basically, the gist of the thread is:
  - code layout and readability should never be sacrificed
  - limit documentation to API's/header files (eg function interfaces, structs)
  - try to be as complete as possible

I'll try to set up a link to a fuller set of guidelines in the near future (now
that I've had a couple of days to catch my breath).

Casey

__________________________________
Do you Yahoo!?
Find out what made the Top Yahoo! Searches of 2003
http://search.yahoo.com/top2003