[Bf-committers] Code documentation

[Ton Roosendaal]

Hi,

Although most people here admit we *should* document more, no serious  
attempts have been made to do this, or organize it in some way. We do  
have a Documentation Board, but they are focusing at end-user docs.
The Documentation Board has defined DocBook as a standard for their  
work, since it also has to become (potentially) available printed. For  
coding docs, plain text or html is acceptable for me.

Since there's hardly no work done on this topic, we'll be happy with  
any initiative to help us out. Why not make a first documentation  
attempt, and post that here for people to review?

Of course someone could also look at reviewing and reorganizing the old  
NaN documentation and/or propose a new structure for it.

-Ton-


On Tuesday, Apr 22, 2003, at 01:17 Europe/Amsterdam, Casey Corn wrote:

> Hello all,
>
> I am seriously interested in documenting the blender
> code, both to help me understand the structure of
> blender, and to help others get started.  I have
> several questions which I hope can be answered here.
>
> First, what are the established procedures for
> documenting the code, beyond what I found at:
>
> http://www.blender.org/modules/documentation/intranet/conventions/ 
> index.html
>
> (which, from my admittedly limited experience, doesn't
> seem to cover a whole lot beyond "use doxygen" :)
>
> Second, what structure is used for the doxygen
> comments?  What goes on the main page, what
> sections/groups/lists/external docs/etc are used?  Has
> anyone here ever used doxygen on large projects
> before?
>
> Also, what is the procedure for submitting
> documentation for the code?  Is there any mechanism
> for reviewing the documentation for correctness?
>
> What are the priorities for documenting the code, if
> any?
>
> What types of stuff needs to be included in the
> documentation?  Stuff like todo lists, bugs, disabled
> features, code cleanups, design goals, etc?
>
> I would really like to help out with this project, but
> I know my coding skills are not (yet) up to hacking on
> the source.  I know how to read c and c++, and am
> learning Python, so I figure that going through the
> code and figuring out what happens and why would be a
> great way to get experience with the ins and outs of
> professional software development.  Why not write down
> what I figure out, to save other newbies the hassle?
>
> Thanks for your time,
> Casey
>
> __________________________________________________
> Do you Yahoo!?
> The New Yahoo! Search - Faster. Easier. Bingo
> http://search.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