Cannot generate API web docs from source
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
Ubuntu HTML5 UI SDK |
Fix Released
|
Medium
|
Kyle Nitzsche | ||
ubuntu-html5-theme (Ubuntu) |
Fix Released
|
Undecided
|
Unassigned |
Bug 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://
* Here's the branch that includes the yuidoc from which that was produced: https:/
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)?
Related branches
Changed in ubuntu-html5-theme: | |
status: | New → Triaged |
assignee: | nobody → Kyle Nitzsche (knitzsche) |
importance: | Undecided → Medium |
Changed in ubuntu-html5-theme: | |
status: | In Progress → Fix Committed |
tags: | added: html5-blocker |
Changed in ubuntu-html5-theme: | |
status: | Fix Committed → Fix Released |
Changed in ubuntu-html5-theme (Ubuntu): | |
status: | Fix Released → Fix Committed |
Changed in ubuntu-html5-theme: | |
status: | Fix Released → In Progress |
Changed in ubuntu-html5-theme (Ubuntu): | |
status: | Fix Committed → In Progress |
Changed in ubuntu-html5-theme: | |
status: | In Progress → Fix Committed |
Changed in ubuntu-html5-theme: | |
status: | Fix Committed → Fix Released |
Changed in ubuntu-html5-theme (Ubuntu): | |
status: | In Progress → Fix Released |
This would be great. I only created the reference documentation on my homepage because the developer documentation was needed for Ubuntu 13.10. Javadoc like documentation is *definitely* the better way to create an API documentation.
YUI doc is in my opinion a very good tool.
If there is interest for it, I could create a branch and import the documention on my homepage in the sourcecode. However, if someone else want to do that, feel free to so.