[Bf-python] Doxygen

[Willian Padovani Germano]

Note: Again, about NMesh: it is not going away.  Use it freely; report
bugs, please.

Hi,

I've made a doxygen test with Camera.c, following instructions sent in
an email to the bf-committers list by Casey Corn in 30 May, the guy who
is doxygenizing parts of Blender.

It is not the documentation we want for the Python API, but it is very
good for documenting exppython source itself.  And since that's the way
other parts of Blender are being documented, it's good to support it.

I'm attaching the results so far, including the modified Camera.c file
(called Camera-doxy.c).  A grouping feature of doxygen was used to
separate Camera Module functions from Camera Type method definitions.  I
haven't updated my linux distro to its just launched version yet and my
doxygen is old, so I can't say whether these results reflect the way a
newer doxygen would format the file.  But the results look fine, so I'm
sending them anyway, just as an example.

If any of you want to run doxygen yourself, edit the
blender/doc/Doxyfile to include Camera-doxy.c, it's easy to find where
and run "doxygen Doxyfile".  The html/ dir will be created there and you
can search for the Camera docs under Scripting.

Probably, there is a way to separate the Python API from the rest of the
functions and then we'd get our API reference doc for free and, most
important, in an automated way.

Repeating just to avoid complaints: the plan is not to have only an API
reference.  Besides it there will be a user friendly doc with:

- Intro about scripting in Blender: what it is, what it can do;

- Short introduction to Python (not a tutorial, only some comments and
links to Python main sites and documentation);

- A page documenting each module: brief explanation of what that modules
deals with and what that is good for in Blender; member variables and 
methods; an example script.

- A final section with some simple but fancy scripts, well commented, to
help newbies.  For example: a basic OpenGL exporter, a Camera setup for
rendering skyboxes, etc.

Note: I changed some things in this Camera-doxy.c file, some names. 
This is just a test because we're already starting layout / name
changes.  Don't worry, it will all be discussed in this list.

BTW: Jordi, I saw where Scene needs Camera.  I'll update its .[ch] files
to only let public declarations in Camera.h, just like other files
needed outsided their .c ones, like the internal Types and recently
Material and Image.  We'll probably end up doing it to all files.

--
Willian, wgermano at ig.com.br
-------------- next part --------------
A non-text attachment was scrubbed...
Name: doxy-test.tgz
Type: application/x-gzip
Size: 30720 bytes
Desc: not available
URL: <http://lists.blender.org/pipermail/bf-python/attachments/20030602/bbd347a1/attachment.bin>