Doc cleanups. Fixes #430.

docs/client/api.html

@@ -61,7 +61,7 @@ <h2 id="publishandsubscribe"><span>Publish and subscribe</span></h2>
 [`unset`](#publish_unset) individual record attributes on a client. These
 methods are provided by `this` in your publish function.
 
-<!-- discuss complete -->
+<!-- TODO discuss complete -->
 
 In particular, if you use [`observe`](#observe) to watch changes to the
 database, be sure to call `this.flush` from inside your observe callbacks.
@@ -186,7 +186,7 @@ <h2 id="publishandsubscribe"><span>Publish and subscribe</span></h2>
     // Subscribe to the chat messages in the current room. Automatically
     // update the subscription whenever the current room changes.
     Meteor.autosubscribe(function () {
-      Meteor.subscribe("chat", {room: Session.get("current-room");});
+      Meteor.subscribe("chat", {room: Session.get("current-room")});
     });
 
 <h2 id="methods_header"><span>Methods</span></h2>
@@ -309,7 +309,7 @@ <h2 id="methods_header"><span>Methods</span></h2>
 
 Finally, if you are inside a stub on the client and call another
 method, the other method is not executed (no RPC is generated, nothing
-"real" happens.)  If that other method has a stub, that stub stands in
+"real" happens).  If that other method has a stub, that stub stands in
 for the method and is executed. The method call's return value is the
 return value of the stub function.  The client has no problem executing
 a stub synchronously, and that is why it's okay for the client to use
@@ -321,7 +321,7 @@ <h2 id="methods_header"><span>Methods</span></h2>
 them on the client (whether from inside a method or at top level), you're
 invoking their stub versions that update the local cache, instead of
 their "real" versions that update the database (using credentials known
-only to the server.)
+only to the server).
 
 {{> api_box meteor_apply}}
 
@@ -349,9 +349,9 @@ <h2 id="connections"><span>Server connections</span></h2>
 <dt><span class="name">status</span>
   <span class="type">String</span></dt>
 <dd>Describes the current reconnection status. The possible
-  values are `connected` (the connection is up and
-  running), `connecting` (disconnected and trying to open a
-  new connection), and `waiting` (failed to connect and
+  values are <code>connected</code> (the connection is up and
+  running), <code>connecting</code> (disconnected and trying to open a
+  new connection), and <code>waiting</code> (failed to connect and
   waiting to try to reconnect).</dd>
 
 <dt><span class="name">retryCount</span>
@@ -363,8 +363,8 @@ <h2 id="connections"><span>Server connections</span></h2>
   <span class="type">Number or undefined</span></dt>
 <dd>The estimated time of the next reconnection attempt. To turn this
   into an interval until the next reconnection, use
-  `retryTime - (new Date()).getTime()`. This key will
-  be set only when `status` is `waiting`.
+  <code>retryTime - (new Date()).getTime()</code>. This key will
+  be set only when <code>status</code> is <code>waiting</code>.
 </dd>
 </dl>
 
@@ -482,7 +482,7 @@ <h2 id="collections"><span>Collections</span></h2>
 
 By default, Meteor automatically publishes every document in your
 collection to each connected client.  To turn this behavior off, remove
-the package:
+the `autopublish` package:
 
     $ meteor remove autopublish
 
@@ -503,7 +503,7 @@ <h2 id="collections"><span>Collections</span></h2>
     // the server.
     assert(Posts.find().count() === 1);
 
-    // Create a temporary, local collection. It works just any other
+    // Create a temporary, local collection. It works just like any other
     // collection, but it doesn't send changes to the server, and it
     // can't receive any data from subscriptions.
     Scratchpad = new Meteor.Collection;
@@ -521,7 +521,7 @@ <h2 id="collections"><span>Collections</span></h2>
 * `$` to denote the matched array position is not
 supported in modifier.
 * Sort does not support subkeys (you can sort on `a`,
-but not `a.b`.)
+but not `a.b`).
 * `findAndModify`, upsert, aggregate functions, and
 map/reduce aren't supported.
 * The supported types are String, Number, Boolean, Array,
@@ -571,7 +571,7 @@ <h2 id="collections"><span>Collections</span></h2>
 
 Add a document to the collection. A document is just an object, and
 its fields can contain any combination of JSON-compatible datatypes
-(arrays, objects, numbers, strings, null, true, and false).
+(arrays, objects, numbers, strings, `null`, true, and false).
 
 `insert` will generate a unique ID for the object you pass, insert it
 in the database, and return the ID.
@@ -704,7 +704,7 @@ <h2 id="collections"><span>Collections</span></h2>
 the raw Mongo modifier that the client wants to execute, for example
 `{$set: {'name.first': "Alice"}, $inc: {score: 1}}`.
 
-Only Mongo modifiers are supported (operations like `$set` and `$push`.)
+Only Mongo modifiers are supported (operations like `$set` and `$push`).
 If the user tries to replace the entire document rather than use
 $-modifiers, the request will be denied without checking the `allow`
 functions.
@@ -786,7 +786,7 @@ <h2 id="collections"><span>Collections</span></h2>
 collection. This is the only effect of insecure mode. If you call `allow` or
 `deny` at all on a collection, even `Posts.allow({})`, then access is checked
 just like normal on that collection. __New Meteor projects start in insecure
-mode by default.__ To turn it off just type `meteor remove insecure`.
+mode by default.__ To turn it off just run `meteor remove insecure`.
 
 {{#note}}
 For `update` and `remove`, documents will be affected only if they match
@@ -985,8 +985,8 @@ <h2 id="meteor_collection_cursor"><span>Cursors</span></h2>
     // Set the 'admin' property on the document to true
     {$set: {admin: true}}
 
-    // Add 2 to the 'votes' property, and add "Traz" to the end of the
-    // 'supporters' array
+    // Add 2 to the 'votes' property, and add "Traz"
+    // to the end of the 'supporters' array
     {$inc: {votes: 2}, $push: {supporters: "Traz"}}
 
 But if a modifier doesn't contain any $-operators, then it is instead
@@ -998,8 +998,7 @@ <h2 id="meteor_collection_cursor"><span>Cursors</span></h2>
     Users.update({_id: "123"}, {name: "Alice", friends: ["Bob"]});
 
 See the [full list of
-modifiers](http://www.mongodb.org/display/DOCS/Updating#Updating-ModifierOperations)
-full list of modifiers.
+modifiers](http://www.mongodb.org/display/DOCS/Updating#Updating-ModifierOperations).
 
 {{/api_box_inline}}
 
@@ -1155,12 +1154,12 @@ <h2 id="accounts_api"><span>Accounts</span></h2>
 
 {{> api_box user}}
 
-Retreives the user record for the current user from
+Retrieves the user record for the current user from
 the [`Meteor.users`](#meteor_users) collection.
 
-On the client this will be a subset of the fields in the document, only
-those that are published from the server are available on the client. By
-default the server publishes `username`, `emails`, and
+On the client, this will be the subset of the fields in the document that
+are published from the server (other fields won't be available on the
+client). By default the server publishes `username`, `emails`, and
 `profile`. See [`Meteor.users`](#meteor_users) for more on
 the fields used in user documents.
 
@@ -1318,7 +1317,7 @@ <h2 id="accounts_api"><span>Accounts</span></h2>
 
 
 Each external service has its own login provider package and login function. For
-example, to support GitHub login, run `$ meteor add accounts-github` and use the
+example, to support GitHub login, run `meteor add accounts-github` and use the
 `Meteor.loginWithGithub` function:
 
     Meteor.loginWithGithub({
@@ -1411,9 +1410,9 @@ <h2 id="accounts_api"><span>Accounts</span></h2>
 
 <h2 id="accounts_passwords"><span>Passwords</span></h2>
 
-The `accounts-password` package contains a full system for password
-based authentication. In addition to the basic username and password
-based sign-in process it also supports email based sign-in including
+The `accounts-password` package contains a full system for password-based
+authentication. In addition to the basic username and password-based
+sign-in process, it also supports email-based sign-in including
 address verification and password recovery emails.
 
 Unlike most web applications, the Meteor client does not send the user's
@@ -1423,15 +1422,15 @@ <h2 id="accounts_passwords"><span>Passwords</span></h2>
 helps protect against embarrassing password leaks if the server's
 database is compromised.
 
-To add password support to your application, run `$ meteor add
+To add password support to your application, run `meteor add
 accounts-password`. You can construct your own user interface using the
 functions below, or use the [`accounts-ui` package](#accountsui) to
-include a turn-key user interface for password based sign-in.
+include a turn-key user interface for password-based sign-in.
 
 
 {{> api_box accounts_createUser}}
 
-On the client this function logs in as the newly created user on
+On the client, this function logs in as the newly created user on
 successful completion. On the server, it returns the newly created user
 id.
 
@@ -1510,15 +1509,15 @@ <h2 id="accounts_passwords"><span>Passwords</span></h2>
 {{> api_box accounts_emailTemplates}}
 
 This is an `Object` with several fields that are used to generate text
-for the emails by `sendResetPasswordEmail`, `sendEnrollmentEmail`, and
-`sendVerificationEmail`.
+for the emails sent by `sendResetPasswordEmail`, `sendEnrollmentEmail`,
+and `sendVerificationEmail`.
 
 Override fields of the object by assigning to them:
 
 - `from`: A `String` with an [RFC5322](http://tools.ietf.org/html/rfc5322) From
-   address. By default email is from `no-reply@meteor.com`. If you wish to
-   receive email from users asking for help with their account, be sure to set
-   this to an email address that you can receive email at.
+   address. By default, the email is sent from `no-reply@meteor.com`. If you
+   wish to receive email from users asking for help with their account, be sure
+   to set this to an email address that you can receive email at.
 - `siteName`: The public name of your application. Defaults to the DNS name of
    the application (eg: `awesome.meteor.com`).
 - `resetPassword`: An `Object` with two fields:
@@ -1685,7 +1684,7 @@ <h2 id="templates_api"><span>Templates</span></h2>
 children, or nodes not rendered by Meteor, use a [constant
 region](#constant) instead.
 
-To preserve nodes, pass a list of selectors each of which should match
+To preserve nodes, pass a list of selectors, each of which should match
 at most one element in the template.  When the template is re-rendered,
 the selector is run on the old DOM and the new DOM, and Meteor will
 reuse the old element in place while working in any HTML changes around
@@ -1786,7 +1785,7 @@ <h2 id="template_inst"><span>Template instances</span></h2>
 
 `Meteor.render` creates a `DocumentFragment` (a sequence of DOM nodes)
 that automatically updates in realtime. Most Meteor apps don't need to
-call this directly, they use templates and Meteor handles the rendering.
+call this directly; they use templates and Meteor handles the rendering.
 
 Pass in `htmlFunc`, a function that returns an HTML
 string. `Meteor.render` calls the function and turns the output into
@@ -2096,7 +2095,13 @@ <h2 id="timers"><span>Timers</span></h2>
 You'll get an error if you call the native function.
 
 {{> api_box setTimeout}}
+
+Returns a handle that can be used by `Meteor.clearTimeout`.
+
 {{> api_box setInterval}}
+
+Returns a handle that can be used by `Meteor.clearInterval`.
+
 {{> api_box clearTimeout}}
 {{> api_box clearInterval}}
 
@@ -2111,8 +2116,8 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 efficient. When you call a function that supports reactive updates
 (say, a database query), it automatically saves the current
 "invalidation context" object if any (say, the current template being
-rendered.) Later, when the data changes, it can "invalidate" this
-context (tell the template to rerender itself.) The whole
+rendered). Later, when the data changes, it can "invalidate" this
+context (tell the template to rerender itself). The whole
 implementation is about 50 lines of code.
 
 Developers, particularly package authors, can use *invalidation
@@ -2137,7 +2142,7 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 [`onInvalidate`](#oninvalidate) to set up a cleanup function so that
 it can know when to stop listening for changes.
 
-Invalidation contexts have an attribute `id` which is a unique positive
+Invalidation contexts have an `id` attribute, which is a unique positive
 integer. You're free to add any other attributes you like to the
 invalidation context for your own convenience, as long as they don't
 start with an underscore.
@@ -2200,7 +2205,7 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 {{> api_box invalidate }}
 
 If this function has already been called on this context, it does
-nothing (a mathematician would say that it is "idempotent.") Otherwise
+nothing (a mathematician would say that it is "idempotent"). Otherwise
 it calls each [`onInvalidate`](#oninvalidate) function registered on
 the context.
 
@@ -2211,7 +2216,7 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 
 If you don't call [`Meteor.flush`](#meteor_flush) explicitly, it will be called
 for you automatically when your code is done running (by setting a
-`setTimeout` timer with a delay of zero.)
+`setTimeout` timer with a delay of zero).
 
 Example:
 
@@ -2223,7 +2228,7 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
     };
 
     // Function to get the temperature (and, if called in a reactive
-    // context, start listening for changes to the temperature.)
+    // context, start listening for changes to the temperature)
     Weather.prototype.getTemp = function () {
       var context = Meteor.deps.Context.current;
 
@@ -2310,22 +2315,22 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 
 `Meteor.flush` forces all of the pending reactive updates to complete
 (for example, it ensures the DOM has been updated with your recent
-database changes.)  Call `flush` to apply those pending changes
+database changes).  Call `flush` to apply those pending changes
 immediately. The main use for this is to make sure the DOM has been
 brought up to date with your latest changes, so you can manually
 manipulate it with jQuery or the like.
 
 When you call `flush`, any auto-updating DOM elements that are not on
 the screen may be cleaned up (meaning that Meteor will stop tracking
 and updating the elements, so that the browser's garbage collector can
-delete them.) So, if you manually call `flush`, you need to make sure
+delete them). So, if you manually call `flush`, you need to make sure
 that any auto-updating elements that you have created by calling
 [`Meteor.render`](#meteor_render) have already been inserted in the main
 DOM tree.
 
 Technically speaking, `flush` calls the [invalidation
 callbacks](#oninvalidate) on every [reactive context](#context) that
-has been [invalidated](#invalidate), but hasn't yet has its callbacks
+has been [invalidated](#invalidate), but hasn't yet had its callbacks
 called. If the invalidation callbacks invalidate still more contexts,
 flush keeps flushing until everything is totally settled. The DOM
 elements are cleaned up by logic that is triggered by context invalidations.
@@ -2335,7 +2340,7 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 <h2 id="meteor_http"><span>Meteor.http</span></h2>
 
 `Meteor.http` provides an HTTP API on the client and server.  To use
-these functions, add the HTTP package to your project with `$ meteor add
+these functions, add the HTTP package to your project with `meteor add
 http`.
 
 {{> api_box httpcall}}
@@ -2383,14 +2388,14 @@ <h2 id="meteor_http"><span>Meteor.http</span></h2>
 
 <dt><span class="name">statusCode</span>
   <span class="type">Number</span></dt>
-<dd>Numeric HTTP result status code, or null on error.</dd>
+<dd>Numeric HTTP result status code, or <code>null</code> on error.</dd>
 
 <dt><span class="name">content</span>
   <span class="type">String</span></dt>
 <dd>The body of the HTTP response as a string.</dd>
 
 <dt><span class="name">data</span>
-  <span class="type">Object or null</span></dt>
+  <span class="type">Object or <code>null</code></span></dt>
 <dd>If the response headers indicate JSON content, this contains the body of the document parsed as a JSON object.</dd>
 
 <dt><span class="name">headers</span>
@@ -2399,7 +2404,7 @@ <h2 id="meteor_http"><span>Meteor.http</span></h2>
 
 <dt><span class="name">error</span>
   <span class="type">Error</span></dt>
-<dd>Error object if the request failed. Matches the `error` callback parameter.</dd>
+<dd>Error object if the request failed. Matches the <code>error</code> callback parameter.</dd>
 
 
 </dl>
@@ -2435,7 +2440,7 @@ <h2 id="meteor_http"><span>Meteor.http</span></h2>
 <h2 id="email"><span>Email</span></h2>
 
 The `email` package allows sending email from a Meteor app. To use it, add the
-package to your project with `$ meteor add email`.
+package to your project with `meteor add email`.
 
 The server reads from the `MAIL_URL` environment variable to determine how to
 send mail. Currently, Meteor supports sending mail over SMTP; the `MAIL_URL`