Reformatted docs for consistency.

Documentation/Books/Users/FoxxBundledApps/OAuth2.mdpp

@@ -2,10 +2,6 @@
 
 The OAuth2 authentication app provides authentication abstractions over OAuth2 providers like Facebook, GitHub and Google. If you want to support additional providers, you can easily define your own.
 
-```js
-var providers = Foxx.requireApp('/_oauth2').providers;
-```
-
 !SECTION Configuration
 
 The app requires no configuration, but you need to update its *providers* collection with your client ID and client secret for each provider you wish to support.
@@ -46,9 +42,17 @@ If you want to use the *google* provider, you need to obtain a client ID and cli
 7. When the Client ID is ready, note down the *Client ID* and *Client secret*.
 8. Update the *google* provider by settiing its *clientId* attribute to the *Client ID* and its *clientSecret* attribute to the *Client secret*. Don't forget to save your changes.
 
-!SECTION Exceptions
+!SECTION JavaScript API: *providers*
 
-!SUBSECTION Provider Not Found
+This app exposes its functionality via a JavaScript API named *providers*.
+
+```js
+var providers = Foxx.requireApp('/_oauth2').providers;
+```
+
+!SUBSECTION Exceptions
+
+!SUBSUBSECTION Provider Not Found
 
 Indicates a provider could not be found in the database.
 
@@ -66,7 +70,7 @@ try {
 }
 ```
 
-!SECTION The provider object
+!SUBSECTION The provider object
 
 Provider objects are instances of a Foxx model with the following attributes:
 
@@ -79,7 +83,7 @@ Provider objects are instances of a Foxx model with the following attributes:
 * *clientId*: the client ID of the app registered with the provider.
 * *clientSecret*: the client secret of the app registered with the provider.
 
-!SECTION List available OAuth2 providers
+!SUBSECTION List available OAuth2 providers
 
 Returns a list of OAuth2 providers that can be presented to the front-end.
 
@@ -101,7 +105,7 @@ var supportedProviders = providers.list().filter(function(obj) {
 });
 ```
 
-!SECTION Define a new OAuth2 provider
+!SUBSECTION Define a new OAuth2 provider
 
 Creates a new OAuth2 provider with the given data.
 
@@ -129,7 +133,7 @@ var provider = providers.create({
 });
 ```
 
-!SECTION Fetch an existing OAuth2 provider
+!SUBSECTION Fetch an existing OAuth2 provider
 
 Fetches an existing OAuth2 provider from the database.
 
@@ -148,14 +152,14 @@ var provider = providers.get('github');
 assertTrue(provider.get('_key'), 'github');
 ```
 
-!SECTION Delete a provider
+!SUBSECTION Delete a provider
 
 There are two ways to delete a provider from the database:
 
 * calling the provider storage's *delete* method with a provider's *_key* directly
 * telling a provider to delete itself
 
-!SUBSECTION Delete a provider by its ID
+!SUBSUBSECTION Delete a provider by its ID
 
 Delete a provider with a given ID.
 
@@ -173,7 +177,7 @@ Attempts to delete the provider with the given *providerId* from the database. I
 providers.delete('github');
 ```
 
-!SUBSECTION Tell a provider to delete itself
+!SUBSUBSECTION Tell a provider to delete itself
 
 Delete a provider from the database.
 
@@ -192,7 +196,7 @@ var provider = providers.get('github');
 provider.delete();
 ```
 
-!SECTION Save a provider
+!SUBSECTION Save a provider
 
 Save a provider to the database.
 
@@ -209,7 +213,7 @@ provider.save();
 ```
 
 
-!SECTION Get the authorization URL of a provider
+!SUBSECTION Get the authorization URL of a provider
 
 Generates the authorization URL for the authorization endpoint of the provider.
 
@@ -223,7 +227,7 @@ Returns a fully-qualified URL for the authorization endpoint of the provider by
 * *args* (optional): an object with any of the following properties:
   * *response_type* (optional): See [RFC 6749](http://tools.ietf.org/html/rfc6749). Default: *"code"*.
 
-!SECTION _getTokenRequest
+!SUBSECTION _getTokenRequest
 
 (Internal.) Generates the token URL and request body for token endpoint of the provider.
 
@@ -241,7 +245,7 @@ Returns an object with two properties:
 * *args* (optional): an object with any of the following properties:
   * *grant_type* (optional): see [RFC 6749](http://tools.ietf.org/html/rfc6749). Default: *"authorization_code"*.
 
-!SECTION Exchange a grant code for an access token
+!SUBSECTION Exchange a grant code for an access token
 
 Exchanges a grant code for an access token.
 
@@ -258,7 +262,7 @@ Throws an exception if the remote server responds with an empty response body.
 * *args* (optional): an object with any of the following properties:
   * *grant_type* (optional): see [RFC 6749](http://tools.ietf.org/html/rfc6749). Default: *"authorization_code"*.
 
-!SECTION Fetch the active user
+!SUBSECTION Fetch the active user
 
 Fetches details of the active user.
 
@@ -281,7 +285,7 @@ var authData = provider.exchangeGrantToken(code, redirect_uri);
 var userData = provider.fetchActiveUser(authData.access_token);
 ```
 
-!SECTION Get a user's identifier
+!SUBSECTION Get a user's identifier
 
 Fetches the user's identifier from a user object returned by the provider.
 

Documentation/Books/Users/FoxxBundledApps/Sessions.mdpp

@@ -2,20 +2,28 @@
 
 The sessions app provides a session storage JavaScript API that can be used in other Foxx apps.
 
-*Configuration*
+!SECTION Configuration
+
+This app has the following configuration options:
 
 * *timeToLive* (optional): number of milliseconds until the session expires. Default: *604800000* (one week).
 * *ttlType* (optional): attribute against which the *timeToLive* is enforced. Valid options: *lastAccess*, *lastUpdate*, *created*. Default: *"created"*.
 * *sidTimestamp* (optional): whether to append a timestamp to the random part of generated session IDs. Default: *false*.
 * *sidLength* (optional): number of random characters to use for new session IDs. Default *20*.
 
+!SECTION JavaScript API: *sessionStorage*
+
+This app exposes a session storage via a JavaScript API named *sessionStorage*.
+
+@EXAMPLES
+
 ```js
 var sessionStorage = Foxx.requireApp('/_sessions').sessionStorage;
 ```
 
-!SECTION Exceptions
+!SUBSECTION Exceptions
 
-!SUBSECTION Session Not Found
+!SUBSUBSECTION Session Not Found
 
 Indicates a session could not be found in the database.
 
@@ -33,7 +41,7 @@ try {
 }
 ```
 
-!SUBSECTION Session Expired
+!SUBSUBSECTION Session Expired
 
 Indicates the session exists in the database but has expired.
 
@@ -52,7 +60,7 @@ try {
 }
 ```
 
-!SECTION The session object
+!SUBSECTION The session object
 
 Session objects are instances of a Foxx model with the following attributes:
 
@@ -63,7 +71,7 @@ Session objects are instances of a Foxx model with the following attributes:
 * *lastAccess*: timestamp of the last time the session was fetched from the database.
 * *lastUpdate*: timestamp of the last time the session was written to the database.
 
-!SECTION Create a session
+!SUBSECTION Create a session
 
 Creates and saves a new instance of the session model.
 
@@ -80,14 +88,14 @@ var session = sessionStorage.create(sessionData);
 assertEqual(session.get('sessionData'), sessionData);
 ```
 
-!SECTION Fetch an existing session
+!SUBSECTION Fetch an existing session
 
 There are two ways to fetch a session via the session storage API:
 
 * resolving a session cookie with the *fromCookie* method
 * calling the session storage's *get* method with a session ID directly
 
-!SUBSECTION Resolve a session cookie
+!SUBSUBSECTION Resolve a session cookie
 
 Fetch a session matching a cookie in a Foxx request.
 
@@ -118,7 +126,7 @@ controller.get('/hello', function(request, response) {
 });
 ```
 
-!SUBSECTION Resolve a session ID directly
+!SUBSUBSECTION Resolve a session ID directly
 
 Fetch a session from the database for a given ID.
 
@@ -136,14 +144,14 @@ Attempts to load the session with the given session ID from the database. If the
 var session = sessionStorage.get(sessionId);
 ```
 
-!SECTION Delete a session
+!SUBSECTION Delete a session
 
 There are two ways to delete a session from the database:
 
 * calling the session storage's *delete* method with a session ID directly
 * telling a session to delete itself
 
-!SUBSECTION Delete a session by its ID
+!SUBSUBSECTION Delete a session by its ID
 
 Delete a session with a given ID.
 
@@ -161,7 +169,7 @@ Attempts to delete the session with the given session ID from the database. If t
 sessionStorage.delete(sessionId);
 ```
 
-!SUBSECTION Tell a session to delete itself
+!SUBSUBSECTION Tell a session to delete itself
 
 Delete a session from the database.
 
@@ -179,7 +187,7 @@ Returns *false* if the session already didn't exist.
 session.delete();
 ```
 
-!SECTION Save a session
+!SUBSECTION Save a session
 
 Save a session to the database.
 
@@ -194,7 +202,7 @@ session.setUser(user);
 session.save();
 ```
 
-!SECTION Set a session's active user
+!SUBSECTION Set a session's active user
 
 Set the active user of a session.
 
@@ -214,7 +222,7 @@ assertEqual(session.get('uid'), user.get('_key'));
 assertEqual(session.get('userData'), user.get('userData'));
 ```
 
-!SECTION Add a session cookie to a response
+!SUBSECTION Add a session cookie to a response
 
 Add a session cookie to a Foxx response.
 
@@ -240,7 +248,7 @@ controller.get('/hello', function(request, response) {
 });
 ```
 
-!SECTION Clear a session cookie
+!SUBSECTION Clear a session cookie
 
 Clear the session cookie of a Foxx response.
 

Documentation/Books/Users/FoxxBundledApps/SimpleAuth.mdpp

@@ -2,16 +2,24 @@
 
 The simple auth app provides hashed password-based authentication with automatically generated salts and constant-time password verification.
 
-*Configuration*
+!SECTION Configuration
+
+This app has the following configuration options:
 
 * *saltLength* (optional): length of newly generated salts. Default: *16*.
 * *hashMethod* (optional): hash algorithm to use. Supported values: *sha1*, *sha224*, *sha256*, *md5*. Default: *"sha256"*.
 
+!SECTION JavaScript API: *auth*
+
+This app exposes its functionality via a JavaScript API named *auth*.
+
+@EXAMPLES
+
 ```js
 var auth = Foxx.requireApp('/_auth').auth;
 ```
 
-!SECTION Generate an authentication object
+!SUBSECTION Generate an authentication object
 
 Generates an authentication object for a given password.
 
@@ -27,7 +35,7 @@ Returns an authentication object with the following properties:
 
 * *password*: the password to hash.
 
-!SECTION Verify a password
+!SUBSECTION Verify a password
 
 Verifies a password against a given authentication object.
 

Documentation/Books/Users/FoxxBundledApps/Users.mdpp

@@ -2,13 +2,19 @@
 
 The users app provides a username-based user storage JavaScript API that can be used in other Foxx apps.
 
+!SECTION JavaScript API: *userStorage*
+
+This app exposes a user storage via a JavaScript API named *userStorage*.
+
+@EXAMPLES
+
 ```js
 var userStorage = Foxx.requireApp('/_users').userStorage;
 ```
 
-!SECTION Exceptions
+!SUBSECTION Exceptions
 
-!SUBSECTION User Not Found
+!SUBSUBSECTION User Not Found
 
 Indicates a user could not be found in the database.
 
@@ -26,7 +32,7 @@ try {
 }
 ```
 
-!SUBSECTION Username Not Available
+!SUBSUBSECTION Username Not Available
 
 Indicates a username is already in use.
 
@@ -44,14 +50,14 @@ try {
 }
 ```
 
-!SECTION The user object
+!SUBSECTION The user object
 
 User objects are instances of a Foxx model with the following attributes:
 
 * *userData*: application-specific user data. This is an arbitrary object that must at least have a *username* property set to the user's username.
 * *authData*: an arbitrary object used by authentication apps to store sensitive data. For password authentication this could be a hash, for third-party authentication services this could be information about the user's identity. This attribute should never be exposed to the user directly.
 
-!SECTION Create a user
+!SUBSECTION Create a user
 
 Creates and saves a new instance of the user model.
 
@@ -70,14 +76,14 @@ var user = userStorage.create({username: 'malaclypse'});
 assertEqual(user.get('userData').username, 'malaclypse');
 ```
 
-!SECTION Fetch an existing user
+!SUBSECTION Fetch an existing user
 
 There are two ways to fetch a user via the user storage API:
 
 * resolving a *username* with the user storage's *resolve* method
 * calling the user storage's *get* method with a user ID directly
 
-!SUBSECTION Resolve a *username*
+!SUBSUBSECTION Resolve a *username*
 
 Fetches a user with a given *username*.
 
@@ -96,7 +102,7 @@ var user = userStorage.resolve('malaclypse');
 assertEqual(user.get('userData').username, 'malaclypse');
 ```
 
-!SUBSECTION Resolve a user ID directly
+!SUBSUBSECTION Resolve a user ID directly
 
 Fetches a user with a given ID.
 
@@ -115,14 +121,14 @@ var user = userStorage.get(userId);
 assertEqual(user.get('_key'), userId);
 ```
 
-!SECTION Delete a user
+!SUBSECTION Delete a user
 
 There are two ways to delete a user from the database:
 
 * calling the user storage's *delete* method with a user ID directly
 * telling a user to delete itself
 
-!SUBSECTION Delete a user by its ID
+!SUBSUBSECTION Delete a user by its ID
 
 Delete a user with a given ID.
 
@@ -140,7 +146,7 @@ Attempts to delete the user with the given user ID from the database. If the use
 userStorage.delete(userId);
 ```
 
-!SUBSECTION Tell a user to delete itself
+!SUBSUBSECTION Tell a user to delete itself
 
 Delete a user from the database.
 
@@ -159,7 +165,7 @@ var user = userStorage.get(userId);
 user.delete();
 ```
 
-!SECTION Save a user
+!SUBSECTION Save a user
 
 Save a user to the database.