api docs

Jump to: navigation, search

API documentation proposal

Summary

Some of the most immediately useful technical content that WPD can provide is for the new JavaScript APIs recently developed (or currently being developed) for web applications. These APIs provide new functionality that make web applications as robust and high-performing as desktop or native apps. By focusing on this area of technical content, we can establish WPD as the leading provider of reference information for modern web development.

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)

On-going work

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."


Examples development

(656 results)

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
Page Summary
apis/MediaStream/ended All tracks of the MediaStream object have ended; the MediaStream is said to be finished.
apis/appcache/ApplicationCache The Application Cache (AppCache) lets web-based applications run offline. Developers can specify resources for the browser to cache, making them available to the application even if no connection can be made to the server. These resources load and work correctly even if users click the refresh button when they are offline.
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.
More results


Review content

(0 results)

These pages need to be reviewed by a community member familiar with the API and its usage in JavaScript. Where you find errors, please correct them; when you're finished, please remove the "Needs Review" flag.

The following criteria are applied:

  • Topics: API
  • High-level issues: Needs Review

Nothing found!


DOM content

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).

Priority API Name Source Description
DOM Pointer Lock API MDN Provides input methods based on the movement of the mouse over time.
DOM Battery MDN Battery status.
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

Additional documents

The methodology for creating API pages is described in WPD:Creating_API_pages.