[compiz] developer documentation work

[David Reveman]

Hey,

Thanks for starting to write some developer documentation. I know that
the lack of good developer documentation is bad. I haven't got around
writing any for two reasons; lack of time and I know that a lot of
things in the current code base will likely change soon, which means
updating and in some cases rewriting any existing documentation.

However, having some documentation now is still very good. Just be aware
that things will change.

-David

On Wed, 2006-06-21 at 19:29 +0300, Tuukka Hastrup wrote:
> Hi all!
> I'm currently working with Compiz and as part of that I'm trying to create
> more developer documentation, as I think that's important in inviting
> both new explorers and bug patches to the project.
> 
> I've started an overview document to go in addition to any existing code
> examples. It's currently available at
> http://iki.fi/Tuukka/2006/summercode/wiki/CompizTechOverview
> 
> Any comments, corrections or additions are welcome either here or in the
> wiki, as I don't have much experience with Compiz or technical writing for
> that matter.
> 
> 
> Another issue I've looked into is code commenting. I know people have
> different feelings about it, but I'd try to explain something about the
> code inline. For example, annotate major branches and loops.
> You can see a start here:
> http://tuukka.iki.fi/cgi-bin/darcs.cgi/compiz/?c=annotate&p=20060621105341-0f16d-055f335f43f5c6ec19f1e30e32725fb202d62925.gz
> 
> On one hand I'm interested in what kind of comments I could get accepted
> into Compiz CVS, on the other hand we could make some external
> code-walk-throughs from left-over comments.
> 
> 
> Last but not least I'm going to document the whole compiz.h interface
> somehow. I haven't started with that yet, and I'm interested in any
> comments on what would be the best way to do that. Internal/external,
> doxygen (JavaDoc/C# syntax) etc.? This is what doxygen can produce
> from the compiz source currently, without additional markup:
> http://tuukka.iki.fi/tmp/compiz-doc
> 
> 
> Regards,
> Tuukka Hastrup
>