[Sugar-devel] Javascript API documentation

[Daniel Narvaez]

By the way, tempted to use this for sugar-docs too. It's not code but even
their site is using it for md files.

We could add a docs command to sugar-build and has_docs/docs_dir properties
to the modules configuration. The run docker on each has_docs module and
output in docs/docs_dir. Finally have buildbot upload docs/ as
developer.sugarlabs.org.

On Wednesday, 15 May 2013, Daniel Narvaez wrote:

> Cool stuff. I don't think we need something very structured and we are
> using markdown for the rest of the docs. I think it's important the docs
> are inside the code, but the usual reference structure makes them boring
> and inflexible.
>
> I think we should go ahead with docker.
>
> On Wednesday, 15 May 2013, Manuel Quiñones wrote:
>
>> 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 ..
>>
>
>
> --
> Daniel Narvaez
>
>

-- 
Daniel Narvaez
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sugarlabs.org/archive/sugar-devel/attachments/20130515/a5723227/attachment-0001.html>