API documentation proposal
The goal for this project is to bring the API documentation up to date and to make WPD the most current source for this documentation.
This proposal outlines a strategy for building out the API documentation, considering the following:
- The current state of the "apis" namespace and extant content
- External content that could be imported to WPD
- New content that will help developers use the latest features of modern browsers
- Creating, updating, and importing content
- Template and forms changes that need to be implemented
- Priorities and project management
- Additional documents
Current state of the WPD API documentation
With the launch of WPD in October 2012, we received a generous donation of API documentation from Microsoft; it included some 12 APIs: appcache, audio-video (media), canvas, file, geolocation, indexeddb, timing, web-messaging, web-storage, websocket, workers, and xhr. A review of this content revealled that it needed to be reorganized and ammended extensively. While this work began, some new API documentation was developed (mostly to prove the process for creating API documentation). The findings of these efforts are summarized in WPD:Creating_API_pages.
The following table summarizes the current state of the extant API documentation on WPD. Note that all of the extant documentation will require changes associated with new templates and forms as discussed in Templates and forms, below. Another (messy) representation of this content may be found on the apis page.
Where the current state is described as "Content complete" the API has been described with all of the pertinent aspects of the current standard specification for that API. It is organized as the API's component model, with objects, properties (attributes), methods, and events delineated accordingly. Additionally, the following checks apply:
- The API_Listing page has instructions for (or a link to the page with the key method or other instructions on) how to use the API.
- The usage of the "key" method is documented and includes example code.
- All objects, properties, methods, and events have pages in the appropriate hierarchy.
- All pages have a summary description.
- All relevant information from the spec is included in the documentation.
- A link to the specification is included.
- All pages are marked "Needs review".
- All pages contain compatibility information if available, or are marked "Compatibility incomplete" if not.
- All pages have topic flags of "API" and API type, e.g., "Web Audio".
The API document may or may not include code examples, and it may or may not have been reviewed; see On-going work.
|Priority||API Name||Handler||Current State|
|1||appcache||Dave Gash||Content complete|
|2||audio-video||Dave Gash||Content complete|
|3||canvas||Dave Gash||Content complete|
|4||css-regions||Mike Sierra||Content complete|
|5||file||Dave Gash||Content complete|
|6||filesystem||Dave Gash||Content complete|
|7||geolocation||Dave Gash||Content complete|
|8||indexeddb||Lance Leonard||In progress|
|9||navigation timing||Dave Gash||Content complete|
|10||user timing||Dave Gash||Content complete|
|11||resource timing||Dave Gash||Content complete|
|12||webaudio||Dave Gash||Content complete|
|13||web-messaging||Dave Gash||Content complete|
|14||webrtc||Scott Rowe||Content complete|
|15||websocket||Dave Gash||Content complete|
|16||web-storage||Dave Gash||Content complete|
|17||workers||Dave Gash||Content complete|
|18||xhr||Dave Gash||Mostly complete, needs to include CORS|
|19||quota management||Dave Gash||Content complete|
|20||gamepad||Dave Gash||Content complete|
|21||canvas WebGL||Scott Rowe||Not started (spec)|
Although the initial layout and development of these documents is complete, a great deal of work remains in developing code examples and reviewing the content. The following tables list the pages that need these pieces in order for the documentation to attain stardom. The lists are the results of queries for content with flags that identify needed improvements; specifically, "Examples Needed" and "Needs Review."
These pages need examples to thoroughly explain the documented API artifacts and their usage. When you've completed a page's example, please remove the "Needs Examples" flag.
The following criteria are applied:
- Topics: API
- Content quality flags: Examples Needed
|apis/MediaStream/ended||All tracks of the MediaStream object have ended; the MediaStream is said to be finished.|
|apis/appcache/ApplicationCache/abort||Cancels the application cache download process. This method is intended to be used by Web applications showing their own caching progress UI, in case the user wants to stop the update (e.g., because bandwidth is limited).|
|apis/appcache/ApplicationCache/oncached||The resources listed in the manifest have been downloaded, and the application is now cached.|
|apis/appcache/ApplicationCache/onchecking||The user agent is checking for an update, or attempting to download the manifest for the first time. This is always the first event in the sequence.|
|apis/appcache/ApplicationCache/ondownloading||The user agent has found an update and is fetching it, or is downloading the resources listed by the manifest for the first time.|
The following criteria are applied:
- Topics: API
- High-level issues: Needs Review
Content identified here was originally considered part of the API project, but these APIs are actually DOM APIs, and should be considered in the scope of the DOM project (yet to be started).
|DOM||Pointer Lock API||MDN||Provides input methods based on the movement of the mouse over time.|
|DOM||MutationObserver||MDN||Observes changes to the DOM.|
|DOM||Page Visibility||MDN||Tells the application if a page is in focus.|
|DOM||Fullscreen||MDN||Gives elements access to fullscreen presentation.|
|DOM||Device Orientation||MDN||Events that signal the device's orientation.|
|DOM||Shadow DOM||Dimitri's Blog||Tip of the Web Components iceberg; Scott is on the hook for this one.|
Creating, updating, and importing content
Along with importing content from other sources, it is crucial that when you are working with existing content you check that content against the source specification. The document, WPD:Creating_API_pages has more information about editing API pages.
Templates and forms
Several issues with the current design and implementation of the templates and forms for use with the API documentation are noted in the "TODO" sections of the page, WPD:Creating_API_pages. The issues are summarized as follows:
- The text fields in the page creation forms on the WPD:New_Page page need to be wider to accomodate longer namespace names. Bug 20625
- We need a better way to specify non-primitive (or uncommon) return types. [Bug 20626]
- Exceptions need to have forms and templates designed for them so that they may be reused between object methods. Bug 20627
- Constants (or enumerations) used as property and method values need to have forms and templates designed for them so that they may be reused between object properties and methods. Bug 20628
- For the Syntax section in properties and methods, it is not clear that the way the form enforces the syntax works in all cases. It may be overly specific. We need a tiger team to look at this more carefully to determine if there is an issue.
- In the Event template it is not clear how the Overview Table gets populated. Looks like the Event template has not been completed. Bug 20629
The methodology for creating API pages is described in WPD:Creating_API_pages.