Cordova docs-gen proposal

cordova-docs-gen.md

Cordova docs-gen proposal

• Use JSDoc for code documentation for following reasons:
  • JSDoc parses code-tree, which means smart code analysis, internal linking and less comments verbosity in code,
  • JSDoc is extensible via JS plugins,
  • JSDoc presentation is customizable via templates,
  • Existing code uses JSDoc format mostly;
• Use either JSDoc or jsdoc-to-markdown to generate documentation HTML/md,
  • In case of jsdoc-to-markdown we will need to set up code linking (it is included by JSDoc by default but not by jsdoc-to-markdown);
• Create JSDoc plugin for handling Cordova-specific tags like supported-platforms, quirks (or windows-quirks, android-quirks, ...), etc.,
  • Investigate possibility: Link to quirks/examples (similar to tutorial tag) instead of inlining to reduce noise in the code (this will also help as existing docs will be moved as is);
• Use custom JSDoc template to integrate with cordova-docs site,
  • The documentation will need to be rebuilt on each code change. Investigate a proper way to do this? (CI tools, precommit hook, prepackage hook for npm).

Upd: Prototype based on camera plugin - docs are generated by jsdoc-to-markdown command.

jsdoc-to-markdown currently does not support jsdoc configuration so that @partial plugin can't be used as is.

Are you proposing we use jsdoc or jsdoc-to-markdown? jsdoc-to-markdown looks quite promising as it has most of what we need - except perhaps some extensibility is that correct?

Overall, this is a good plan - let's try this with a simple plugin - like device and share with the community.

This would be best implemented as a standalone tool to generate a Markdown file from a given plugin repo. Right now a plugin's docs live in its README.md (e.g. cordova-plugin-file), and having a generated file would be very useful. It would be great if we could run a command like this to generate the docs for a plugin:

generate-plugin-docs.js cordova-plugin-file > cordova-plugin-file-doc.md

This file would use JSDoc, or whatever else you choose, and we could have it live under the docs bin folder.