Bug 589090 - Convert page-worker doc to apidoc format. r=myk, a0.7=myk
authorDrew Willcoxon <adw@mozilla.com>
Fri, 20 Aug 2010 23:09:55 -0700
changeset 753 14a18be1a7c0aa8ec02118ba5baf4ebbe59e4121
parent 752 c87b3fbe08971e9c5097034c9faa83132d5dccc8
child 754 3851d63dda7b3c41da0a2a8f368984a79b0cde75
push id281
push userdwillcoxon@mozilla.com
push dateSat, 21 Aug 2010 06:13:32 +0000
reviewersmyk
bugs589090
Bug 589090 - Convert page-worker doc to apidoc format. r=myk, a0.7=myk
packages/jetpack-core/docs/page-worker.md
--- a/packages/jetpack-core/docs/page-worker.md
+++ b/packages/jetpack-core/docs/page-worker.md
@@ -1,106 +1,117 @@
+<!-- contributed by Felipe Gomes [felipc@gmail.com] -->
+
 The `page-worker` module provides a way to create a permanent, invisible
 page and access its DOM.
 
-## Initialization and usage ##
 
-<code>`require`(*"page-worker"*).**Page**(*options*)</code>
-
-Creates an uninitialized Page Worker instance.
-
-The `options` parameter is optional, and if given it should be an object
-with any of the following keys:
-
-<table>
-  <tr>
-    <td><code>content</code></td>
-    <td>
-      A string which represents the initial content of the Page Worker. It can
-      be either an URL to be loaded or a piece of HTML code to be used as the
-      content for the page.
-    </td>
-  </tr>
-  <tr>
-    <td><code>onReady</code></td>
-    <td>
-      A function callback or an array of functions that will be called when
-      the DOM on the page is ready. This can be used to know when your
-      Page Worker instance is ready to be used, and also whenever the page
-      is reloaded or another page is loaded in its place.
-    </td>
-  </tr>
-    <tr>
-    <td><code>allow</code></td>
-    <td>
-      An object with keys to configure the permissions on the Page Worker.
-      The boolean key "script" controls if scripts from the page
-      are allowed to run. The default value is false.
-    </td>
-  </tr>
-
-</table>
+Constructors
+------------
 
-<code>`require`(*"page-worker"*).**add**(*Page Worker*)</code>
-
-Initialize the given Page Worker instance. You'll only be able to use its
-features after calling this function, which will define its properties
-as described in the API reference below.
-
-<code>`require`(*"page-worker"*).**remove**(*Page Worker*)</code>
-
-Unload the given Page Worker instance. After you remove a Page Worker, its
-memory is freed and you must create a new instance if you need to load
-another page.
-
-## Properties ##
-
-<code>page.**window**</code>
-
-The `window` object of the page
-
-<code>page.**document**</code>
-
-The `document` object of the page
-
-<code>page.**onReady**</code>
-
-A function callback or an array of functions that will be called when
-the DOM on the page is ready. This can be used to know when your
-Page Worker instance is ready to be used, and also whenever the page
-is reloaded or another page is loaded in its place.
-
-<code>page.**content**</code>
-
-A string which represents the content of the Page Worker. It can
-be either an URL to be loaded or a piece of HTML code to be used as the
-content for the page.
-
-<code>page.**allow**</code>
-An object with keys to configure the permissions on the Page Worker.
-The boolean key "script" controls if scripts from the page
-are allowed to run.
+<api name="Page">
+@constructor
+  Creates an uninitialized Page Worker instance.
+@param [options] {object}
+  The *`options`* parameter is optional, and if given it should be an object
+  with any of the following keys:
+  @prop [content] {string}
+    A string which represents the initial content of the Page Worker. It can
+    be either a URL to be loaded or a piece of HTML code to be used as the
+    content for the page.
+  @prop [onReady] {function,array}
+    A function callback or an array of functions that will be called when
+    the DOM on the page is ready. This can be used to know when your
+    Page Worker instance is ready to be used, and also whenever the page
+    is reloaded or another page is loaded in its place.
+  @prop [allow] {object}
+    An object with keys to configure the permissions of the Page Worker.
+    The boolean key `script` controls if scripts from the page
+    are allowed to run. Its default value is false.
+</api>
 
 
-## Examples ##
+Functions
+---------
+
+<api name="add">
+@function
+  Initialize the given Page Worker instance. You'll only be able to use its
+  features after calling this function, which will define its properties
+  as described in the Page Objects section below.
+@param pageWorker {Page}
+  The Page Worker instance to initialize.
+</api>
+
+<api name="remove">
+@function
+  Unload the given Page Worker instance. After you remove a Page Worker, its
+  memory is freed and you must create a new instance if you need to load
+  another page.
+@param pageWorker {Page}
+  The Page Worker instance to unload.
+</api>
+
+
+Page Objects
+------------
+
+Once they have been initialized by calling `add()`, Page Worker instances have
+the following properties:
+
+<api name="window">
+@property {object}
+  The `window` object of the page.
+</api>
 
-### Example - Print all header titles from a Wikipedia article ###
+<api name="document">
+@property {object}
+  The `document` object of the page.
+</api>
+
+<api name="onReady">
+@property {collection}
+  A function callback or an array of functions that will be called when
+  the DOM on the page is ready. This can be used to know when your
+  Page Worker instance is ready to be used, and also whenever the page
+  is reloaded or another page is loaded in its place.
+</api>
+
+<api name="content">
+@property {string}
+  A string which represents the content of the Page Worker. It can
+  be either a URL to be loaded or a piece of HTML code to be used as the
+  content for the page.
+</api>
+
+<api name="allow">
+@property {object}
+  An object with keys to configure the permissions on the Page Worker.
+  The boolean key `script` controls if scripts from the page
+  are allowed to run.
+</api>
+
+
+Examples
+--------
+
+### Print all header titles from a Wikipedia article ###
 
 First, don't forget to import the module:
 
-    var PageWorker = require("page-worker");
-    
+    var pageWorker = require("page-worker");
+
 Then, create a page pointed to Wikipedia and add it
 to the page workers:
 
-    var page = PageWorker.Page({
+    var page = pageWorker.Page({
       content: "http://en.wikipedia.org/wiki/Internet",
       onReady: printTitles
     });
-    PageWorker.add(page);
+    pageWorker.add(page);
 
 And define the function to print the titles:
 
     function printTitles() {
       var elements = this.document.querySelectorAll("h2 > span");
       for (var i = 0; i < elements.length; i++) {
         console.log(elements[i].textContent);
       }