I created a branch http://bugs.dojotoolkit.org/browser/branches/jsdoc
to test JSDoc style comments in our source code, rather than our
proprietary format.
Running it through the JSDoc Toolkit parser yields results in:
http://bill.dojotoolkit.org/jsdoc/
The conversion seems doable, which isn't surprising given that all the
other toolkits are already using this format. There are some gotchas
with jsdoc-toolkit though:
- class names with an underscore don't work, needed to rename _Widget to
Widget, etc.
- missing keywords: protected, readonly, callback, extension
------------
I then moved on to google closure compiler. Closure compiler has it's
own requirements; for example, the type specification needs to match
http://code.google.com/closure/compiler/docs/js-for-compiler.html#types.
After updating _Widget.js to make the closure compiler happy, I'm able
to use closure compiler in both simple and advanced mode:
36769 original _Widget.js
9403 shrinksafed _Widget.js
8184 closure compiler simple mode
5597 closure compiler advanced mode
That's a pretty impressive compression improvement, although I think to
really test it we would need to convert all of our code to JSDoc format,
including all the dojo core modules, not just the few dijit files I
converted. Still, worth more investigation.
In _Templated.js I'm getting lots of warnings about the use of "this",
etc. Seems closure doesn't understand @lends and therefore isn't
understanding dojo.declare(). I'm not sure what to do about that. Maybe
just adding @this metadata for every method, but I'm uneasy about
closure not understanding our classes. Looks like google doesn't use
anything like dojo.declare, see for example
http://code.google.com/p/closure-library/source/browse/trunk/closure/goog/fx/abstractdragdrop.js
towards the bottom, or
http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml).
