[Sugar-devel] Javascript API documentation

[Manuel Quiñones]

2013/5/15 Manuel Quiñones <manuq at laptop.org>:
> 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)

- Javadoc-like docs can be a pain to write without a specific IDE like Eclipse

/me just remembered his bad experiences with Java :)

--
.. manuq ..