[Sugar-devel] Javascript API documentation

[Daniel Narvaez]

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 <javascript:;>>:
> > 2013/5/14 Daniel Narvaez <dwnarvaez at gmail.com <javascript:;>>:
> >> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sugarlabs.org/archive/sugar-devel/attachments/20130515/28ed124d/attachment.html>