[Bf-committers] Doxygen project

[Casey Corn]

Hi Ton,

--- Ton Roosendaal <ton@blender.org> wrote:
> Hi,
> 
<snip!>
> > wrote, except for one thing: source/blender/src .
> > This is where I personally have the most difficult
> > time understanding the code (am I the only one?).
> 
> And that's especially the code to leave alone, at
> least for a while...  
> you can find the associated include files in the  
> source/blender/include/ BTW.

Didn't know they had .h files 8^o .  Objection
withdrawn.

> I noticed an attempt to doxy mainqueue.c, which
> contains experimental code which was supposed to
> start a restructuring, something that was  never
> finished.  Doxy conventions really don't fit this
> code.  Currently I am fixing all little quirks in
> the OSX port, which closely relate to this code.
> While getting more confident with it again, I'll
> decide to either:
> 
> - write docs!
> - restructure it all!

It might be a good idea to do both :) .  That is,
write barebones docs to help you restructure.  An
added benefit is that other people can provide
opinions on how and what to restructure (if the docs
are easily accessible).  Also, the docs will be 100%
correct ;) .

<snip!>
> Please rewind the doxy for mainqueue.c or other c
> files you did here.

I will roll all the .c files I committed back a rev as
soon as I get a chance (should this include
creator.c?).  This might be a while (at school, finals
are in less than two weeks (eek!)), but I will try to
find the time.  For the record, cgul posted the docs
for mainqueue.c and others (which I then committed) in
the documentation forum:

http://www.blender.org/modules.php?op=modload&name=phpBB2&file=viewtopic&t=1498

I will roll these back, as well.  This was before the
decision to only document .h files.  Thinking about
it, I should have replaced "The documentor (me)" with
"The documentor (cgul)".  I'll admit that I didn't
closely review the docs for correctness, since I had
never even looked at the mainqueue.c file before, and
there were no guidelines to follow.  Now that there
*are* guidelines in place, I can check submissions
from other people against them.  I don't know if I can
check for 100% correctness, however, since the code
others document may be beyond me (although,
considering the ammount of people who have submitted
docs, this may not be an issue).

<snip!>
> 
> Sorry for the rant, not meant negative! :)
> 
> -Ton-

Don't be sorry!  Any feedback at all helps to shape my
and other's documentation efforts.  If you and Nathan
are the only one with feedback, well then you will be
the major shaper of the doxygen documents!  You said
in an earlier e-mail that you are not the
representative coder, but if no one else provides
input, no one else has the right to complain ;) .

Would anyone care if I ask for more feedback in the
forums now? or should I wait for more input from here
first?  I would post the guidelines that have been
discussed so far (which probably wouldn't be a bad
idea even if I didn't ask for feedback).

Again, thanks for the comments.
Casey


__________________________________
Do you Yahoo!?
Yahoo! Calendar - Free online calendar with sync to Outlook(TM).
http://calendar.yahoo.com