From 14ea8dcb06b6d844dd99b7e18cca99172bea0cfd Mon Sep 17 00:00:00 2001
From: Luke Smith <lsmith@yahoo-inc.com>
Date: Sat, 16 Jul 2011 00:42:29 -0700
Subject: [PATCH] Minor doc fixes, edits

---
 .../datasource-local-debug.js                 | 34 ++++----
 build/datasource-local/datasource-local.js    | 34 ++++----
 src/console/docs/index.mustache               |  6 +-
 src/dataschema/docs/index.mustache            | 75 ++++++++++++++----
 src/datasource/docs/index.mustache            | 79 +++++++------------
 src/datasource/js/datasource-local.js         | 34 ++++----
 src/jsonp/docs/index.mustache                 | 38 +++++++--
 src/stylesheet/docs/index.mustache            | 12 ++-
 8 files changed, 193 insertions(+), 119 deletions(-)

diff --git a/build/datasource-local/datasource-local-debug.js b/build/datasource-local/datasource-local-debug.js
index 799d81fcde8..e23d80560a6 100644
--- a/build/datasource-local/datasource-local-debug.js
+++ b/build/datasource-local/datasource-local-debug.js
@@ -189,13 +189,16 @@ Y.extend(DSLocal, Y.Base, {
          * </dd>
          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
          * <dt>data (Object)</dt> <dd>Raw data.</dd>
-         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
-         *     <dl>
-         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
-         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
-         *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
-         *     </dl>
-         * </dd>
+         * <dt>response (Object)</dt>
+         *     <dd>Normalized response object with the following properties:
+         *         <dl>
+         *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
+         *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
+         *             <dt>error (Boolean)</dt> <dd>Error flag.</dd>
+         *         </dl>
+         *     </dd>
+         * <dt>error</dt>
+         *     <dd>Any error that occurred along the transaction lifecycle.</dd>
          * </dl>
          * @preventable _defResponseFn
          */
@@ -220,13 +223,16 @@ Y.extend(DSLocal, Y.Base, {
          * </dd>
          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
          * <dt>data (Object)</dt> <dd>Raw data.</dd>
-         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
-         *     <dl>
-         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
-         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
-         *         <dt>error (Object)</dt> <dd>Error object.</dd>
-         *     </dl>
-         * </dd>
+         * <dt>response (Object)</dt>
+         *     <dd>Normalized response object with the following properties:
+         *         <dl>
+         *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
+         *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
+         *             <dt>error (Object)</dt> <dd>Error object.</dd>
+         *         </dl>
+         *     </dd>
+         * <dt>error</dt>
+         *     <dd>Any error that occurred along the transaction lifecycle.</dd>
          * </dl>
          */
 
diff --git a/build/datasource-local/datasource-local.js b/build/datasource-local/datasource-local.js
index a8553ab6a84..2401e43ff83 100644
--- a/build/datasource-local/datasource-local.js
+++ b/build/datasource-local/datasource-local.js
@@ -189,13 +189,16 @@ Y.extend(DSLocal, Y.Base, {
          * </dd>
          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
          * <dt>data (Object)</dt> <dd>Raw data.</dd>
-         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
-         *     <dl>
-         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
-         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
-         *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
-         *     </dl>
-         * </dd>
+         * <dt>response (Object)</dt>
+         *     <dd>Normalized response object with the following properties:
+         *         <dl>
+         *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
+         *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
+         *             <dt>error (Boolean)</dt> <dd>Error flag.</dd>
+         *         </dl>
+         *     </dd>
+         * <dt>error</dt>
+         *     <dd>Any error that occurred along the transaction lifecycle.</dd>
          * </dl>
          * @preventable _defResponseFn
          */
@@ -220,13 +223,16 @@ Y.extend(DSLocal, Y.Base, {
          * </dd>
          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
          * <dt>data (Object)</dt> <dd>Raw data.</dd>
-         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
-         *     <dl>
-         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
-         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
-         *         <dt>error (Object)</dt> <dd>Error object.</dd>
-         *     </dl>
-         * </dd>
+         * <dt>response (Object)</dt>
+         *     <dd>Normalized response object with the following properties:
+         *         <dl>
+         *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
+         *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
+         *             <dt>error (Object)</dt> <dd>Error object.</dd>
+         *         </dl>
+         *     </dd>
+         * <dt>error</dt>
+         *     <dd>Any error that occurred along the transaction lifecycle.</dd>
          * </dl>
          */
 
diff --git a/src/console/docs/index.mustache b/src/console/docs/index.mustache
index dc84cc401f7..1a5b075cbf6 100755
--- a/src/console/docs/index.mustache
+++ b/src/console/docs/index.mustache
@@ -371,10 +371,10 @@ YUI().use('console','overlay', function (Y) {
 </p>
 
 ```
-<script src="http://yui.yahooapis.com/{$yui3CurrentVersion}/build/yui/yui-min.js"></script>
+<script src="http://yui.yahooapis.com/{{yuiVersion}}/build/yui/yui-min.js"></script>
 <!-- Include debug messages from the node module -->
-<script src="http://yui.yahooapis.com/{$yui3CurrentVersion}/build/node/node-debug.js"></script>
-<script type="text/javascript">
+<script src="http://yui.yahooapis.com/{{yuiVersion}}/build/node/node-debug.js"></script>
+<script>
 YUI().use('overlay', function (Y) {
     // Overlay requires Node.  Any other missing dependencies are automatically
     // loaded, excluding node-min.js since the node module  is already provided
diff --git a/src/dataschema/docs/index.mustache b/src/dataschema/docs/index.mustache
index 1e06fd9c448..0bf22a9b975 100644
--- a/src/dataschema/docs/index.mustache
+++ b/src/dataschema/docs/index.mustache
@@ -1,5 +1,12 @@
 <div class="intro">
-    <p>The DataSchema Utility applies a given schema against data of arbitrary formats, normalizing input such as JSON, XML, or delimited text into a JavaScript object with known properties. The value of the DataSchema Utility is in its ability to translate data from a variety of sources into a consistent format for consumption by components in a predictable manner.</p>
+    <p>
+        The DataSchema Utility applies a given schema against data of arbitrary
+        formats, normalizing input such as JSON, XML, or delimited text into a
+        JavaScript object with known properties. The value of the DataSchema
+        Utility is in its ability to translate data from a variety of sources
+        into a consistent format for consumption by components in a predictable
+        manner.
+    </p>
 </div>
 
 {{>getting-started}}
@@ -10,7 +17,11 @@
 
 <h3 id="basics">DataSchema basics</h3>
 
-<p>DataSchema classes are standalone static utilities that accept data input plus a schema definition and return a JavaScript object with the following properties:</p>
+<p>
+    DataSchema classes are standalone static utilities that accept data input
+    plus a schema definition and return a JavaScript object with the following
+    properties:
+</p>
 
 <table>
 <thead>
@@ -34,11 +45,17 @@
 </tbody>
 </table>
 
-<p>Note that the schema you define will depend on which subclass of DataSchema is being used.</p>
+<p>
+    Note that the schema you define will depend on which subclass of DataSchema
+    is being used.
+</p>
 
 <h4 id="array">DataSchema.Array</h4>
 
-<p>Use DataSchema.Array when working with JavaScript arrays. These arrays may contain JavaScript objects, other arrays, or primitive values.</p>
+<p>
+    Use DataSchema.Array when working with JavaScript arrays. These arrays may
+    contain JavaScript objects, other arrays, or primitive values.
+</p>
 
 ```
 // A sample array of objects
@@ -61,7 +78,7 @@
 ];
 ```
 
-<p>Define a schema with the following properties for your array data:
+<p>Define a schema with the following properties for your array data:</p>
 
 <table>
 <thead>
@@ -91,7 +108,11 @@ var myOutput = Y.DataSchema.Array.apply(mySchema, myData));
 
 <h4 id="json">DataSchema.JSON</h4>
 
-<p>Use DataSchema.JSON when working with JavaScript objects or JSON data. Typically, your data will hold meta values as well as an internal array of tabular data.</p>
+<p>
+    Use DataSchema.JSON when working with JavaScript objects or JSON data.
+    Typically, your data will hold meta values as well as an internal array of
+    tabular data.
+</p>
 
 ```
 // Sample JSON data
@@ -117,7 +138,11 @@ var myOutput = Y.DataSchema.Array.apply(mySchema, myData));
 };
 ```
 
-<p>Locators are string values in your schema that use dot notation or bracket syntax to point to data values within the object. Define a schema with the following properties for your object data:</p>
+<p>
+    Locators are string values in your schema that use dot notation or bracket
+    syntax to point to data values within the object. Define a schema with the
+    following properties for your object data:
+</p>
 
 <table>
 <thead>
@@ -159,12 +184,18 @@ var myOutput = Y.DataSchema.JSON.apply(mySchema, myData));
 
 <h4 id="xml">DataSchema.XML</h4>
 
-<p><strong>Note:</strong> XML parsing currently has known issues on the Android WebKit browser.
+<p>
+    <strong>Note:</strong> XML parsing currently has known issues on the
+    Android WebKit browser.
+</p>
 
-<p>Use DataSchema.XML when working with XML data. As with JSON data, your XML data may hold meta values as well as an internal node list of tabular data.</p>
+<p>
+    Use DataSchema.XML when working with XML data. As with JSON data, your XML
+    data may hold meta values as well as an internal node list of tabular
+    data.
+</p>
 
 ```
-$xml = <<<END
 // Sample XML data
 <Response>
     <Session>542235629</Session>
@@ -187,7 +218,11 @@ $xml = <<<END
 </Response>
 ```
 
-<p>Locators are XPath string values in your schema that point to data values within the XML. Define a schema with the following properties for your XML data:</p>
+<p>
+    Locators are XPath string values in your schema that point to data values
+    within the XML. Define a schema with the following properties for your XML
+    data:
+</p>
 
 <table>
 <thead>
@@ -229,7 +264,10 @@ var myOutput = Y.DataSchema.XML.apply(mySchema, myData));
 
 <h4 id="text">DataSchema.Text</h4>
 
-<p>Use DataSchema.Text when working with delimited textual data. Typically, your data will not contain meta values.</p>
+<p>
+    Use DataSchema.Text when working with delimited textual data. Typically,
+    your data will not contain meta values.
+</p>
 
 ```
 // Sample text data
@@ -279,7 +317,13 @@ var myOutput = Y.DataSchema.Text.apply(mySchema, myData));
 
 <h3 id="plugin">DataSchema as a DataSource plugin</h3>
 
-<p>DataSchema plugins integrate DataSource's retrieval functionality with schema-based normalization of the retrieved data for further consumption by another component. There are currently four available DataSource plugins: DataSourceArraySchema, DataSourceJSONSchema, DataSourceXMLSchema, and DataSourceTextSchema.</p>
+<p>
+    DataSchema plugins integrate DataSource's retrieval functionality with
+    schema-based normalization of the retrieved data for further consumption by
+    another component. There are currently four available DataSource plugins:
+    DataSourceArraySchema, DataSourceJSONSchema, DataSourceXMLSchema, and
+    DataSourceTextSchema.
+</p>
 
 ```
 myDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
@@ -298,4 +342,7 @@ myDataSource.sendRequest({
 
 <h2 id="knownissues">Known Issues</h2>
 
-<p><strong>Known Android issues (bugs 2529621, 2529758, 2529775):</strong> XML parsing is currently buggy on the Android WebKit browser.</p>
+<p>
+    <strong>Known Android issues (bugs 2529621, 2529758, 2529775):</strong> XML
+    parsing is currently buggy on the Android WebKit browser.
+</p>
diff --git a/src/datasource/docs/index.mustache b/src/datasource/docs/index.mustache
index 518808dd9c9..b5f86b9018a 100755
--- a/src/datasource/docs/index.mustache
+++ b/src/datasource/docs/index.mustache
@@ -247,68 +247,45 @@ YUI().use("datasource-function", "datasource-polling", function(Y) {
     <tr>
         <td><code>request</code></td>
         <td>Request is made.</td>
-        <td><dl>
-            <dt><code>tId</code></dt>
-            <dd>Unique transaction ID.</dd>
-            <dt><code>request</code></dt>
-            <dd>The request value.</dd>
-            <dt><code>callback</code></dt>
-            <dd>The callback object.</dd>
-            <dt><code>cfg</code></dt>
-            <dd>The configuration object.</dd>
-       </dl></td>
+        <td>
+            <dl>
+                <dt><code>tId</code></dt>
+                    <dd>Unique transaction ID.</dd>
+                <dt><code>request</code></dt>
+                    <dd>The request value.</dd>
+                <dt><code>callback</code></dt>
+                    <dd>The callback object.</dd>
+                <dt><code>cfg</code></dt>
+                    <dd>The configuration object.</dd>
+            </dl>
+       </td>
     </tr>
     <tr>
         <td><code>data</code></td>
         <td>Raw data is received from the source.</td>
-        <td><dl>
-            <dt><code>tId</code></dt>
-            <dd>Unique transaction ID.</dd>
-            <dt><code>request</code></dt>
-            <dd>The request value.</dd>
-            <dt><code>callback</code></dt>
-            <dd>The callback object.</dd>
-            <dt><code>cfg</code></dt>
-            <dd>The configuration object.</dd>
-            <dt><code>data</code></dt>
-            <dd>The raw data.</dd>
-        </dl></td>
+        <td>
+            All properties from `request` plus
+            <dl>
+                <dt><code>data</code></dt>
+                    <dd>The raw data.</dd>
+            </dl>
+        </td>
     </tr>
     <tr>
         <td><code>response</code></td>
         <td>Response is returned to a callback function.</td>
-        <td><dl>
-            <dt><code>tId</code></dt>
-            <dd>Unique transaction ID.</dd>
-            <dt><code>request</code></dt>
-            <dd>The request value.</dd>
-            <dt><code>callback</code></dt>
-            <dd>The callback object.</dd>
-            <dt><code>cfg</code></dt>
-            <dd>The configuration object.</dd>
-            <dt><code>data</code></dt>
-            <dd>The raw data.</dd>
-            <dt><code>response</code></dt>
-            <dd>Data normalized into a response object.</dd>
-        </dl></td>
+        <td>
+            All properties from `data` plus
+            <dl>
+                <dt><code>response</code></dt>
+                    <dd>Data normalized into a response object.</dd>
+            </dl>
+        </td>
     </tr>
     <tr>
         <td><code>error</code></td>
-        <td>An error is encountered</td>
-        <td><dl>
-            <dt><code>tId</code></dt>
-            <dd>Unique transaction ID.</dd>
-            <dt><code>request</code></dt>
-            <dd>The request value.</dd>
-            <dt><code>callback</code></dt>
-            <dd>The callback object.</dd>
-            <dt><code>cfg</code></dt>
-            <dd>The configuration object.</dd>
-            <dt><code>data</code></dt>
-            <dd>The raw data.</dd>
-            <dt><code>response</code></dt>
-            <dd>Data normalized into a response object.</dd>
-        </dl></td>
+        <td>After `response` event, before the configured failure callback is executed.</td>
+        <td>Same properties as the `response` event</td>
     </tr>
 </tbody>
 </table>
diff --git a/src/datasource/js/datasource-local.js b/src/datasource/js/datasource-local.js
index 6f3bcd4220a..f5e3f9a338f 100755
--- a/src/datasource/js/datasource-local.js
+++ b/src/datasource/js/datasource-local.js
@@ -187,13 +187,16 @@ Y.extend(DSLocal, Y.Base, {
          * </dd>
          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
          * <dt>data (Object)</dt> <dd>Raw data.</dd>
-         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
-         *     <dl>
-         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
-         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
-         *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
-         *     </dl>
-         * </dd>
+         * <dt>response (Object)</dt>
+         *     <dd>Normalized response object with the following properties:
+         *         <dl>
+         *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
+         *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
+         *             <dt>error (Boolean)</dt> <dd>Error flag.</dd>
+         *         </dl>
+         *     </dd>
+         * <dt>error</dt>
+         *     <dd>Any error that occurred along the transaction lifecycle.</dd>
          * </dl>
          * @preventable _defResponseFn
          */
@@ -218,13 +221,16 @@ Y.extend(DSLocal, Y.Base, {
          * </dd>
          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
          * <dt>data (Object)</dt> <dd>Raw data.</dd>
-         * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
-         *     <dl>
-         *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
-         *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
-         *         <dt>error (Object)</dt> <dd>Error object.</dd>
-         *     </dl>
-         * </dd>
+         * <dt>response (Object)</dt>
+         *     <dd>Normalized response object with the following properties:
+         *         <dl>
+         *             <dt>results (Object)</dt> <dd>Parsed results.</dd>
+         *             <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
+         *             <dt>error (Object)</dt> <dd>Error object.</dd>
+         *         </dl>
+         *     </dd>
+         * <dt>error</dt>
+         *     <dd>Any error that occurred along the transaction lifecycle.</dd>
          * </dl>
          */
 
diff --git a/src/jsonp/docs/index.mustache b/src/jsonp/docs/index.mustache
index 6d8b1a35b5b..5f35a2917fc 100755
--- a/src/jsonp/docs/index.mustache
+++ b/src/jsonp/docs/index.mustache
@@ -147,21 +147,39 @@ YUI.Env.JSONP.yui_3_3_0_1_1294184187597423({"foo":"bar"});
     <tbody>
         <tr>
             <td>timeout</td>
-            <td>This value, defined as milliseconds, is a time threshold for the transaction (e.g., <code>{ timeout: 2000 }</code> ). When this limit is reached, the transaction's <code>on.timeout</code> callback will be executed if supplied.</td>
+            <td>
+                This value, defined as milliseconds, is a time threshold for
+                the transaction (e.g., <code>{ timeout: 2000 }</code> ). When
+                this limit is reached, the transaction's
+                <code>on.timeout</code> callback will be executed if
+                supplied.
+            </td>
         </tr>
         <tr>
             <td>context</td>
-            <td>Defines what will be &quot;<code>this</code>&quot; in the callbacks.  If undefined, the default will be the JSONPRequest instance.</td>
+            <td>
+                Defines what will be &quot;<code>this</code>&quot; in the
+                callbacks.  If undefined, the default will be the JSONPRequest
+                instance.
+            </td>
         </tr>
         <tr>
             <td>args</td>
-            <td>An array of additional arguments that will be passed to the callbacks as second, third, and so on arguments.</td>
+            <td>
+                An array of additional arguments that will be passed to the
+                callbacks as second, third, and so on arguments.
+            </td>
         </tr>
         <tr>
-            <td>on (required)</td>
-            <td><p>This object defines the callbacks to be used for the transaction.  At least an <code>on.success</code> handler must be defined.</p>
+            <td>on</td>
+            <td>
+                <p>
+                    <strong>Required</strong>. This object defines the
+                    callbacks to be used for the transaction.  At least an
+                    <code>on.success</code> handler must be defined.
+                </p>
                 <ul>
-                    <li>success (required)</li>
+                    <li>success (<strong>required</strong>)</li>
                     <li>failure</li>
                     <li>timeout</li>
                 </ul>
@@ -169,7 +187,13 @@ YUI.Env.JSONP.yui_3_3_0_1_1294184187597423({"foo":"bar"});
         </tr>
         <tr>
             <td>format</td>
-            <td>Preprocessor function to stitch together the supplied URL (first argument), the proxy function name (internally generated), and any additional arguments passed to <code>send()</code>.  See <a href="#format">Customizing the JSONP URL</a> for more detail.</td>
+            <td>
+                Preprocessor function to stitch together the supplied URL
+                (first argument), the proxy function name (internally
+                generated), and any additional arguments passed to
+                <code>send()</code>.  See <a href="#format">Customizing the
+                JSONP URL</a> for more detail.
+            </td>
         </tr>
     </tbody>
 </table>
diff --git a/src/stylesheet/docs/index.mustache b/src/stylesheet/docs/index.mustache
index 6a0cbc62810..6598ffa11a1 100644
--- a/src/stylesheet/docs/index.mustache
+++ b/src/stylesheet/docs/index.mustache
@@ -397,11 +397,19 @@ sheet.enable();
 </thead>
 <tbody>
     <tr>
-        <td><a href="../api/StyleSheet.html#method_StyleSheet.register"><code>register(instance, name)</code></a></td>
+        <td>
+```
+Y.StyleSheet.register(instance, name)
+```
+        </td>
         <td>Use to assign a named registry entry for a StyleSheet instance.</td>
     </tr>
     <tr>
-        <td><a href="../api/StyleSheet.html#method_StyleSheet.toCssText"><code>toCssText(property_obj, starting_cssText)</code></a></td>
+        <td>
+```
+Y.StyleSheet.toCssText(property_obj, starting_cssText)
+```
+        </td>
         <td>Use to translate an object of style property:value pairs to a single <code>cssText</code> string.  The optional second argument is a <code>cssText</code> string of a style's &quot;before&quot; state.</td>
     </tr>
 </tbody>