[Bf-committers] CVS commit: blender/source/creator buildinfo.c creator.c

[Casey Corn]

Ton,

> Great, you've made a start. Can you provide us a
> sort-of schedule?
Schedules are hard for me to keep, because I don't
have as much time to devote to blender as I'd like. 
My personal goal is to document one or two files a
day, which isn't much considering that blender
contains 500+ source files in just the source/blender
directory :( (not counting [read/write]streamglue,
[en/de]crypt, [in/de]flate, makesdna - in your earlier
post you recommened avoiding these directories)

> As I wrote before, safe parts to start documenting
are:
> 
> - ghost
> - (in fact all libraries in intern)
A good portion of files in the intern directory
already have some doxygen comments in them.  I've
already added c api of ghost to the docs.  Regarding
ghost: there is already a \mainpage tag in the sources
and a doxygen config file template in ghost/doc which
tells me that someone has already spent time on
documenting ghost.  I could probably figure out how to
generate the docs using the template file (it looks as
if a ghost makefile substitutes things like blender
versions and root directories to make a real config
file).  However, it might be more efficient to ask
whoever made the docs to do it :)

> - imbuf
I'm starting to document all the files in this
directory.  I don't know yet if I'll be able to do
some of the image format specific stuff without a bit
of research (which takes more time).  There are about
50 files in this directory (not counting makefiles and
CVS files) so I expect that in a month or two this
will be done.
> - radiosity
> - blenkernel
> - render

After I finish imbuf, I'll probably do the next three
you have listed, in that order.  There are around 150
files in these three directories, so that is about 3-5
months at a rate one or two files per day.

After that I'll probably start doing:
source/blender/blenlib
source/blender/blenloader
source/blender/[read/write]blenfile
source/blender/avi
source/blender/img

Also, I might doc some files and random functions in
source/blender/src, especially GUI and hotkey stuff.

I will also review and commit any docs that anyone
else submits.  Any help I can get will speed things up
of course.

I'm totally open to suggestions.  I will be glad to do
anything that needs to be done, such as documents to
help people get started in blender or to help out in
development.  Since I'm still sorting through the
source code myself, however, I don't know what will be
the most help (that's why I'm just iterating thru the
directories).

Oh, and previous to joining this list I had studied
the creator.c file, and so I just mostly copy/pasted
those docs into the source.  I also doc'ed the other
file in source/creator (buildinfo.c) for completeness.

Well, that's about it.  I hope that this is what you
were asking for ;).

Casey

P.S.
I will almost never change the actual code.  The only
exception I will make is when changing the code
slightly will make documentation possible.  For
instance, in source/blender/imbuf/IMB_imbuf_types.h,
in the struct ImBuf, the x and y dims are declared:

	short x,y; /* width in pixels, height in scanlines */

This makes documenting the individual variables
difficult and error prone using doxygen, so I will
change it to:

	short x; /**< Width in pixels */
	short y; /**< Height in scanlines */

This is okay, right?

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