[Sugar-devel] Javascript API documentation

[Manuel Quiñones]

2013/5/14 Daniel Narvaez <dwnarvaez at gmail.com>:
> Hello,
>
> I think we should write a reference for the javascript API as we develop it.
> It's always hard to find time to do that after the fact and documenting it
> will help to come up with a better API.

Good point Daniel, I was going to suggest the same.

> Unless someone has alternatives to suggest (I have not spent much time
> investigating the topic), we should probably just use YUIdoc. It looks like
> a fine tool, it does what we need and it's based on nodejs like every other
> tool we are using.

I've been looking at literate programming [1][2] doc generators.  They
generate annotated source.  I've seen them used in a number of
javascript projects like Jasmine and CoffeeScript.

[1] http://jashkenas.github.io/docco/
[2] http://jbt.github.io/docker/src/docker.js.html

This is another approach to documentation than JSDoc and YUIdoc, and I
think it serves a slightly different purpose.

The literate programming docs:

- are useful for the developers too, can be an entry point for contributors
- don't need a very structured syntax with @tags, less work to do (and
we are still few)
- @tags that can be a bit redundant (marking a private member @private
for example)

On the other hand, great that you pointed me to YUIdoc, because I was
contrasting Docco with JSDoc and it looked a bit obsolete.  So that
was another point for docco in my little research.

Maybe YUIdoc (or any Javadoc-like doc generator) is more suitable to
discribe APIs?  Specially considering hooking other systems like
Android in the future?

> We can setup sugar-build/buildbot to generate the docs and upload them.

Yes! The URL could be http://developer.sugarlabs.org/reference

--
.. manuq ..