Add in-code documentation

[GoogleCodeExporter]

Sean, et all.,

I’ve created an in-code documentation system for iui.js, similar in concept
to Javadocs but similar in syntax to Python’s ReStructured Text (though
dramatically simplified). In order to avoid adding a dependency on a
ReST-to-HTML converter like sphinx, I wrote a simple script to support a
simplified version of ReST.

Using this system, I wrote a full iUI Documentation, including all the iui
public properties and methods, as well as the custom events iUI fires and
the events iUI subscribes to. You can view this in the patch or at
http://www.projectrecon.net/iui/iui_docs.html

I also wrote a separate Getting Started Tutorial, for a gentler
introduction to iUI, you can view this in the patch or at
http://www.projectrecon.net/iui/getting-started.html

This patch is also located at http://www.bitbucket.org/PeterRust/iui.

The documentation-generation script is in the /docs/ folder and is called
refresh_docs.py. It can be run by any computer with python installed
(includes almost all linux distros) with the command “python 
refresh_docs.py”.

I would appreciate any feedback and especially
contributions/improvements/corrections to the Documentation & Getting
Started Tutorial – and of course I would love to see them pulled into the
official iUI tip on Google Code.

-- Peter Rust
Developer, Cornerstone Systems

PS: I didn’t find this thread about an iUI manual until after I’d created
this, but fortunately it appears that what I’ve done is mostly in-line with
some of the desires expressed there (though of course it isn’t a full manual).

PPS: On an iUI thread someone recommended Microsoft's format for Javascript
in-code comments
(http://weblogs.asp.net/bleroy/archive/2007/04/23/the-format-for-javascript-doc-
comments.aspx).
While I'm open to switching the documentation from (Python's ReST-style) to
the JSDoc-style (inspired by Javadoc) and using either
http://jsdoc.sourceforge.net/ or http://code.google.com/p/jsdoc-toolkit/, I
would prefer not to use Microsoft's format (the xml-based syntax adds too
much visual clutter).

Original issue reported on code.google.com by PeterAndJessica@gmail.com on 3 Jun 2010 at 9:59

Attachments:

• iui-docs.diff

[GoogleCodeExporter]

I've wanted to add an in-code documentation system for some time now.  I'd 
prefer to use one of the standard systems rather than a home-brew.  I'd also 
like to use one that integrates well with the ANT build.

That said, since you've done the work and appear willing to support it, I'm in 
favor integrating your changes.  It's possible in the future we might want to 
switch to another JSDoc format, but given that we've gone this long without 
adding one it could be quite a while before we switch.

We'll have to merge the comments into the iui.js from the msgilligan-iscroll 
branch at some point, too.

Original comment by msgilli...@gmail.com on 11 Jun 2010 at 3:01

• Changed state: Accepted

[GoogleCodeExporter]

> I'd prefer to use one of the standard systems rather than a home-brew
Agreed, jsdoc-toolkit (v2) would be my preference (runs on Rhino's Javascript 
engine, which I think GAE includes -- or something close to it). It includes a 
templating system, so the output is very flexible -- I like the CodeView 
template (http://www.thebrightlines.com/article-data/images/codeview-1.jpg), 
but we'd probably want to modify the template (or create one) to match the new 
site.

Original comment by PeterAndJessica@gmail.com on 11 Jun 2010 at 5:44

[GoogleCodeExporter]

I've committed the code to Hg.  I'm happy with the current solution for now, 
let's go with it!

jsdoc-toolkit could be a good solution.  Rhino-based should makes it work well 
with ANT.  I'm also interested in trying to "compile" iUI with Google's closure 
compiler.

Original comment by msgilli...@gmail.com on 11 Jun 2010 at 10:14

• Changed state: Started