[sugar] Sugar API documentation

[Bernie Innocenti]

Edward Cherlin wrote:

>>  And when I say "documentation", I mean "a handful of awesome activities
>>  that are copiously documented in a literate programming style."
> 
> I am a professional API tech writer, and I have been a developer. I
> would be delighted to work on this, if I could get the support I need.
> What do the developers use now?

I talked about it with Marco on IRC.  Some documentation is done with
gtk-doc because of our extensive use of the Gnome APIs.  We are not
opposed to switch to something else (Doxygen, Epydoc) if there seems
to be benefits and someone volunteers to do the conversion.

Checkout the main Sugar repository and have a look yourself:
  git clone git://dev.laptop.org/sugar

There are plenty of other related projects that could use some love.

Personally, I think documenting these low-level details and the
internals of Sugar has a low effort/utility ratio.  The code base
seemed sufficiently understandable even the first time I've looked
at it.

There's much more value in clearly describing the overall architecture,
the interaction between Sugar and Activities, the various DBus
protocols, etc.  Some of this exists in wiki.latop.org, but much of
this information is incomplete, disorganized or just bitrotting.

So, rather than the API-oriented fine-grained documentation (which
may be a lot of to revise and extend), I'd like to see the stuff in
the wiki reorganized and revised to assume the form of a comprehensive,
top-down developer manual for the Sugar environment.

My non-pro $0.02 opinion.  Edward, what do you think about it?

-- 
   \___/
  _| o |  Bernie Innocenti - http://www.codewiz.org/
  \|_X_|  "It's an education project, not a laptop project!"