| 2013-10-17 21:49:49 |
Kyle Nitzsche |
description |
Today, we cannot generate JavaScript API web docs for from the source JavaScript.
(A community member (Daniel Beck thanks!) has put together an excellent set of pages [1] instructing how to use the Ubuntu HTML5 widgets including overall explanation, the JavaScript API, and some content on CSS. But these appear hand-crafted and not generated from source. )
It seems important to be able to generate API docs from source automatically for at least these reasons:
* Automation and maintenance: When a new version is released, there should be a clear path to generating the API docs and publishing them, with no handcrafting required
* Engineering responsibility: placing the API doc content in the source itself clearly makes engineers who change the API responsible for keeping the API docs synchronized
To this end, I implemented a first pass at adding comments to source such that API docs can be generated. I used yuidoc format.
* Here's what is generated today: http://people.canonical.com/~knitzsche/yuidoc-ubuntu-html5-theme/17oct2013/
* Here's the branch that includes the yuidoc from which that was produced: https://code.launchpad.net/~knitzsche/ubuntu-html5-theme/ubuntu-html5-theme-yuidoc
Some parts are not yet done (lists.js, toolbars.js, popovers. fastbuttons.js)
Many are "done" to first pass level: core.js, pagestack.js, tabs.js, dialogs.js, buttons.js.
The generated web pages are (obviously) not Ubuntu themed, which can be changed.
Is there a good reason to use a different system (jsdoc for instance)?
[1] http://daniel-beck.org/ubuntu-html5-theme/widgets/ |
Today, we cannot generate JavaScript API web docs for from the source JavaScript.
(A community member (Daniel Beck thanks!) has put together an excellent set of pages [1] instructing how to use the Ubuntu HTML5 widgets including overall explanation, the JavaScript API, and some content on CSS. But these appear hand-crafted and not generated from source. )
It seems important to be able to generate API docs from source automatically for at least these reasons:
* Automation and maintenance: When a new version is released, there should be a clear path to generating the API docs and publishing them, with no handcrafting required
* Engineering responsibility: placing the API doc content in the source itself clearly makes engineers who change the API responsible for keeping the API docs synchronized
To this end, I implemented a first pass at adding comments to source such that API docs can be generated. I used yuidoc format.
* Here's what is generated today: http://people.canonical.com/~knitzsche/yuidoc-ubuntu-html5-theme/17oct2013/
* Here's the branch that includes the yuidoc from which that was produced: https://code.launchpad.net/~knitzsche/ubuntu-html5-theme/ubuntu-html5-theme-yuidoc
Some parts are not yet done (lists.js (now done), toolbars.js, popovers. fastbuttons.js)
Many are "done" to first pass level: core.js, pagestack.js, tabs.js, dialogs.js, buttons.js.
The generated web pages are (obviously) not Ubuntu themed, which can be changed.
Is there a good reason to use a different system (jsdoc for instance)?
[1] http://daniel-beck.org/ubuntu-html5-theme/widgets/ |
|
