Simple Python tool to extract Closure-style JSDoc from Closure-style codebases and prepare a API reference in HTML.
The existing Closure API docs were released around the time the Closure Tools suite was open sourced. It's a system very tied up with Grok, which is great, but is largely proprietary and cannot be open sourced.
There had been some effort to repurpose Closure Linter's parsers and tokenizers to do this job, but it turned out somewhat more difficult than expected to reuse that code, and the effort stalled and was eventually abandoned.
Other JsDoc systems kind of work on Closure, but the flag/type syntax used by Closure is foreign to these tools.
I, nanaze, wanted to take a shot at doing this in a more lo-fi manner, possibly repurposing an existing parser like Esprima. But quick prototyping led me to extract JsDoc with regular expressions in Python which, though duct-tape-like, works surprisingly well and quickly. Update: I have begun migrating over to esprima and pulling symbol/JSDoc info from the resulting AST. This work is in esprima.py, genfiletree.py, processfiletree.py
These are explicit decisions made to keep the codebase small and simple:
- Support Closure-style JSDoc. And that's it -- no generalization for different JSDoc dialects for the sake
- Fail fast with errors, not warnings -- if parser or doc generator sees a problem, it pukes, as there's something with your code. Writing a test to verify that docs build on each checkin/commit is encouraged.
The tool is not done. Enough is implemented at present to identify all JSDoc'd symbols in the current Closure codebase and extract the associated JSDoc comments.
Right now, the tool can do minimal rendering to HTML. The following needs to be implemented:
- Rendering of functions.
- Inheritance
- "this.foo" properties
- lots more
If you'd like to contribute, let me know by sending an email.