Decent source code documentation frameworks have been around since a long time for real programming languages like C or Java. Some even have documentation built-in. I believe it's due to the fact that since very recently nobody really wrote large amounts of JavaScript that needed to be maintained.
Fortune has it though, that we do have a huge (and growing) amount of JS code to maintain and have changed documentation frameworks twice already. Coming from a hand-made doc-framework based on doxygen, we realized it wasn't able to handle the dynamicality and paradigms of JavaScript so we moved to the flexible Naturaldocs. Naturaldocs didn't really 'understand' JavaScript which meant for us to clutter the code with a lot of "explanatory" markup. So we went on to jsdoc-toolkit just recently. Still it seems the journey is not over yet. The toolkit does not understand the way we define classes in our code so we need to manually markup classes and inheritance in comments which are cluttering again. Hopefully we can add those through plugins:
- Support for our complex namespace hierarchy
- A decent output template
- Support to parse our class definitions including extension and mixins
Jsdoc-toolkit is written in JavaScript and runs in rhino which definitely is a plus since we converted our build-system to JavaScript as well.
*Forget about stupidity, discover your ability.
Posted by: Taobao buy | 01/17/2011 at 08:05 AM
HesY8I Good point. I hadn't thought about it quite that way. :)
Posted by: Essie | 04/09/2011 at 05:06 AM
i have this thing, why is it that javascript is visible when you try to view the sourcecode? is there a way to hide the javascript code when someone try to view your code?
Posted by: grey scrubs | 08/15/2011 at 05:30 AM