Skip to content
Browse files
Adds plugin documentation generation proposal
  • Loading branch information
daserge committed May 19, 2016
1 parent 7872ce6 commit 06f044b8af17fada66dbef11aa4530b3bedfbe25
Showing 1 changed file with 39 additions and 0 deletions.
@@ -0,0 +1,39 @@
# Cordova docs-gen proposal

## Intro

Cordova plugins documentation currently live separated from source code so that sync issues can occur on commits.
Proposed solution uses [JSDoc]( to generate a plugin API docs, while allows to wrap the generated docs into template (markdown with handlebars partials) with extra-details like Quirks or additional examples.

## Libraries/frameworks used

* [jsdoc-to-markdown](

Proposal is currently implemented for cordova-plugin-camera only: [generated doc result](


* A nice TOC helps in understanding what APIs are exposed,
* A better structure for args with a table showing default values,
* Hyperlinks for type definitions,
* Literate programming makes sense - docs & code remain together,
* A common plugin [template]( that is shared among all cordova official plugins including basic details such as:
* How to install,
* Where to file bugs,
* Where to discuss design questions,
* Provide a pointer to slack plugins community,
* Buildbot badge.


* Requires a generation script before every commit

**Summary instructions**:

* Put a template including license, header, install steps and extra docs (quirks) to `jsdoc2md/`,
* Document `www` folder source code using JSDoc,
* [Mark all template extra-docs sections, which will be linked to as an `<a>` with `name`](,
* [Link JSDocs to the template' extra docs sections](,
* Call `npm install` to install dev dependencies,
* Call [npm run gen-docs]( to generate the documentation,
* Docs generation script will also be called [automatically*]( via [husky]( precommit hook (*`npm install` is required).

0 comments on commit 06f044b

Please sign in to comment.