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.<div> </div><div>I think we should go ahead with docker. On Wednesday, 15 May 2013, Manuel Quiñones wrote: <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> 2013/5/15 Manuel Quiñones <<a href="javascript:;" onclick="_e(event, 'cvml', 'manuq@laptop.org')">manuq@laptop.org</a>>: > 2013/5/14 Daniel Narvaez <<a href="javascript:;" onclick="_e(event, 'cvml', 'dwnarvaez@gmail.com')">dwnarvaez@gmail.com</a>>: >> 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] <a href="http://jashkenas.github.io/docco/" target="_blank">http://jashkenas.github.io/docco/</a> > [2] <a href="http://jbt.github.io/docker/src/docker.js.html" target="_blank">http://jbt.github.io/docker/src/docker.js.html</a> > > 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 .. </blockquote></div> -- Daniel Narvaez