Bug 589104 - Convert selection doc to apidoc format. r=myk, a0.7=myk
authorDrew Willcoxon <adw@mozilla.com>
Fri, 20 Aug 2010 23:11:05 -0700
changeset 754 3851d63dda7b3c41da0a2a8f368984a79b0cde75
parent 753 14a18be1a7c0aa8ec02118ba5baf4ebbe59e4121
child 755 494344c7ce7cbfbf9cd798bb337ecf92c9c550c4
push id281
push userdwillcoxon@mozilla.com
push dateSat, 21 Aug 2010 06:13:32 +0000
reviewersmyk
bugs589104
Bug 589104 - Convert selection doc to apidoc format. r=myk, a0.7=myk
packages/jetpack-core/docs/selection.md
--- a/packages/jetpack-core/docs/selection.md
+++ b/packages/jetpack-core/docs/selection.md
@@ -1,71 +1,88 @@
-The `selection` module provides a means to get and set current text/HTML
-selections, as well as observe new selections.
+<!-- contributed by Eric H. Jung [eric.jung@yahoo.com] -->
 
-## Properties ##
-
-<tt>selection.**text**</tt>
+The `selection` module provides a means to get and set text and HTML selections
+in the current Firefox page.  It can also observe new selections.
 
-Gets or sets the current selection as plain text. Setting the selection
-removes all current selections, inserts the specified text at the location
-of the first selection, and selects the new text. Getting the selection when
-there is no current selection returns <tt>null</tt>. Setting the selection
-when there is no current selection throws an exception. Getting the selection
-when **contiguous** is <tt>true</tt> returns the text of the first selection.
+It does not currently support selections inside `textarea` and `input` elements,
+however.
+
+
+Properties
+----------
 
-<tt>selection.**html**</tt>
+<api name="text">
+@property {string}
+  Gets or sets the current selection as plain text. Setting the selection
+  removes all current selections, inserts the specified text at the location of
+  the first selection, and selects the new text. Getting the selection when
+  there is no current selection returns `null`. Setting the selection when there
+  is no current selection throws an exception. Getting the selection when
+  `contiguous` is `true` returns the text of the first selection.
+</api>
 
-Gets or sets the current selection as HTML. Setting the selection removes
-all current selections, inserts the specified text at the location of the
-first selection, and selects the new text. Getting the selection when there
-is no current selection returns <tt>null</tt>. Setting the selection
-when there is no current selection throws an exception. Getting the selection
-when **contiguous** is <tt>true</tt> returns the text of the first selection.
-
-<tt>selection.**contiguous**</tt>
-
-Getter which returns <tt>true</tt> if the current selection is a single,
-contiguous selection.  Returns <tt>false</tt> if there are two or more discrete
-selections, each of which may or may not be spatially adjacent. If there is no
-current selection, <tt>null</tt> is returned.  Discontiguous selections
-can be created interactively with <tt>Ctrl+click-and-drag</tt>.
+<api name="html">
+@property {string}
+  Gets or sets the current selection as HTML. Setting the selection removes all
+  current selections, inserts the specified text at the location of the first
+  selection, and selects the new text. Getting the selection when there is no
+  current selection returns `null`. Setting the selection when there is no
+  current selection throws an exception. Getting the selection when `contiguous`
+  is `true` returns the text of the first selection.
+</api>
 
-### Registering for Selection Notification ###
-
-To be notified of selections, define one or more functions and assign them
-to the **onSelect** property. Each function will be called back after a
-selection is completed.
+<api name="contiguous">
+@property {boolean}
+  `true` if the current selection is a single, contiguous selection, and `false`
+  if there are two or more discrete selections, each of which may or may not be
+  spatially adjacent. If there is no current selection, this property is `null`.
+  (Discontiguous selections can be created by the user with
+  Ctrl+click-and-drag.)
+</api>
 
-Usage for a single callback:
+<api name="onSelect">
+@property {collection}
+  A collection of selection listeners.  Each is a function that will be called
+  when a selection is made.  See Registering for Selection Notification below.
+</api>
 
-    selection.onSelect = function() {};
 
-Adds the specified anonymous function to a list of callbacks which are called
-when text/HTML is selected.
+Registering for Selection Notifications
+---------------------------------------
 
-Usage for multiple callbacks:
+To be notified when the user makes a selection, define one or more functions and
+add them to the `onSelect` collection. Each function will be called back after a
+selection is made.
 
-    selection.onSelect = [function() {}, function() {}];
+To add functions, pass them to `onSelect.add()`:
 
-Adds the specified anonymous functions to a list of callbacks which are
-called when text/HTML is selected.
+    function myCallback() {
+      console.log("A selection has been made.");
+    }
+    var selection = require("selection");
+    selection.onSelect.add(myCallback);
+    selection.onSelect.add([myCallback2, myCallback3]);
 
-<tt>selection.onSelect.**remove**(*callback*)</tt>
+To remove functions, pass them to `onSelect.remove()`:
 
-Removes *callback* from the list of callbacks which are called when text/HTML
-is selected.
+    selection.onSelect.remove(myCallback);
+    selection.onSelect.remove([myCallback2, myCallback3]);
 
-### Iterating Over Discontiguous Selections ###
+
+Iterating Over Discontiguous Selections
+---------------------------------------
 
-Discontiguous selections can be accessed by iterating over
-<tt>selection</tt>. Each iteration instance returns a <tt>Selection</tt> object
-on which <tt>text</tt>, <tt>html</tt>, or <tt>contiguous</tt> may be called.
+Discontiguous selections can be accessed by iterating over the `selection`
+module itself. Each iteration yields a `Selection` object from which `text`,
+`html`, and `contiguous` properties can be accessed.
 
-## Examples ##
+
+Examples
+--------
 
 Log the current contiguous selection as text:
 
     var selection = require("selection");
     if (selection.text)
       console.log(selection.text);
 
 Log the current discontiguous selections as HTML:
@@ -75,12 +92,11 @@ Log the current discontiguous selections
       for (var subselection in selection) {
          console.log(subselection.html);
       }
     }
 
 Surround HTML selections with delimiters:
 
     var selection = require("selection");
-    selection.onSelect.add(function() {
-        selection.html = "\\\" + selection.html + "///";
+    selection.onSelect.add(function () {
+      selection.html = "\\\" + selection.html + "///";
     };
-