move documentation into javascript source

[lloyd]

An initial experiment with yuidoc suggests to me that we could use the yuidoc_parse.py module with very few modifications to extract documentation from javascript source and build up a json datastructure.

This would afford some clear (in my mind) benefits:

• move documentation next to implementation to give it a better chance of staying up to date
• provide a structured and thought through mechanism to document methods, parameters, and events
• give us a clean way to implement a full api search within the documentation (I personally find this to be a pretty important discovery tool)

I think we could also leave markdown formatted comments inside javascript files and use showdown to render them.

wanted to capture the idea here, as right now the documentation feels very browse oriented and disparate from source...

[lloyd]

oh, and one thing I don't like about this change is that it introduces a significant difference between modules in chromeless and addon-kit, which makes moving them back and forth more difficult.

[dangoor]

I just spotted this tool last night:
https://github.com/visionmedia/dox

haven't tried it yet, but it sounds nice on the surface

[taboca]

I do not see the difference. I mean, when we build the actual documentation asset via parsing the JS should not cause any impact to others JS modules that don't have the feature. We would simply be populating additional documentation, and properly mixing it into existing MD-based docs, from the modules. Another thing now, in Chromeless, is that a lot of our samples are now HTML+JS. So another questions is if want to build documentation from these individual "modules" that are not really modules yet, HTML + JS samples and tests. Another aspect for discussion are tests. Could our tests also be incorporated back to the documentation too? At least the state of tests ( OK/Not OK ).

[lloyd]

@dangoor - That does look interesting. The only catch is I was thinking that something in python would integrate better. I've got some early success in repurposing the yuidoc stuff.

@taboca - I agree that our modules would still be compatible with jetpack, but I'm proposing doing away with all of the separate .md files for module documentation and moving everything into source. So that would mean that you'd have to manually munge documentation to move modules back and forth. Not a huge deal, and maybe we can offer up our patches to the addon-kit project?

[lloyd]

integrate new documentation system which parses docs out of javascript source. Closed by 420f86a