diff --git a/README.md b/README.md
index 17dcd44..991cf0f 100644
--- a/README.md
+++ b/README.md
@@ -147,21 +147,29 @@ Stable API
 
 <!-- hooks -->
 
-* `OAUTH3.utils.clientUri(window.location);` produces the default `client_uri` of your app (also used as `client_id`)
-* `OAUTH3.discover(providerUri, { client_id: clientUri });` Promises the config file for the provider and caches it in memory.
-* `OAUTH3.implicitGrant(providerUri, { client_id: clientUri })` returns a `session` with `session.token.sub` as the secure ppid.
-  * `debug: true` will cause the windows to not refresh automatically
-  * `windowType: 'popup'` will use a popup window to ask user for new permissions, if any
-  * `windowType: 'background'` will automatically log the user in (if all permissions have been accepted)
-* `OAUTH3.request({ method: 'GET', url: '', session: '', data: '' })` make an authenticated request to a resource
-* `OAUTH3.logout(providerUri, { client_id: clientUri, session: session })` opens a popup to confirm logout from the provider
-  * Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this
-* `OAUTH3.urls.discover(providerUri, { client_id: clientUri })` generates a correctly parameterized url
-* `OAUTH3.urls.implicitGrant(directives, { client_id: clientUri })` generates a correctly parameterized url
-* `OAUTH3.urls.refreshToken(directives, opts)` generates a correctly parameterized url
-  * `opts.client_id = clientUri`
-  * `opts.access_token = <jwt>`
-  * `opts.refresh_token = <jwt>`
+```
+OAUTH3.utils.clientUri(window.location);                    // produces the default `client_uri` of your app (also used as `client_id`)
+
+OAUTH3.discover(providerUri, { client_id: clientUri });     // Promises the config file for the provider and caches it in memory.
+
+OAUTH3.implicitGrant(providerUri, { client_id: clientUri }) // returns a `session` with `session.token.sub` as the secure ppid.
+  // debug: true - will cause the windows to not refresh automatically
+  // windowType: 'popup' - will use a popup window to ask user for new permissions, if any
+  // windowType: 'background' - will automatically log the user in (if all permissions have been accepted)
+
+OAUTH3.request({ method: 'GET', url: '', session: '', data: '' })       // make an authenticated request to a resource
+
+OAUTH3.logout(providerUri, { client_id: clientUri, session: session })  // opens a popup to confirm logout from the provider
+  // Note: you should probably clear your own storage (i.e. localStorage, indexedDb) whenever you call this
+
+OAUTH3.urls
+  .discover(providerUri, { client_id: clientUri })          // generates a correctly parameterized url
+  .implicitGrant(directives, { client_id: clientUri })      // generates a correctly parameterized url
+  .refreshToken(directives, opts)                           // generates a correctly parameterized url
+      // opts.client_id = clientUri
+      // opts.access_token = <jwt>
+      // opts.refresh_token = <jwt>
+```
 
 <!-- TODO implicit grant broker -->
 <!-- TODO logout specific user -->
@@ -178,16 +186,18 @@ DO NOT rely on them. Many of them WILL change (we just wanted to publish with th
 
 Public utilities for browser and node.js:
 
-* `OAUTH3.jwt`
-  * `OAUTH3.jwt.decode('<urlSafeBase64-encoded-json-web-token>');         // { iat, iss, aud, sub, exp, ttl }
+```
+OAUTH3.jwt
+  .decode('<urlSafeBase64-encoded-json-web-token>');          // { iat, iss, aud, sub, exp, ttl }
 
-* `OAUTH3.utils`
-  * `OAUTH3.utils.query.stringify({ access_token: '...', debug: true });  // access_token=...&debug=true`
-  * `OAUTH3.utils.scope.stringify([ 'profile', 'contacts' ]);             // 'profile,contacts'`
-  * `OAUTH3.utils.uri.normalize('https://oauth3.org/connect/');           // 'oauth3.org/connect'`
-  * `OAUTH3.utils.url.normalize('oauth3.org/connect/');                   // 'https://oauth3.org/connect'`
-  * `OAUTH3.utils.url.resolve('oauth3.org/connect/', '/api/');            // 'https://oauth3.org/connect/api'`
-  * `OAUTH3.utils.atob('<non-urlsafe-base64-string>');                    // '<binary-string>' (typically json ascii)`
+OAUTH3.utils
+  .query.stringify({ access_token: '...', debug: true });     // access_token=...&debug=true
+  .scope.stringify([ 'profile', 'contacts' ]);                // 'profile,contacts'
+  .uri.normalize('https://oauth3.org/connect/');              // 'oauth3.org/connect'
+  .url.normalize('oauth3.org/connect/');                      // 'https://oauth3.org/connect'
+  .url.resolve('oauth3.org/connect/', '/api/');               // 'https://oauth3.org/connect/api'
+  .atob('<non-urlsafe-base64-string>');                       // '<binary-string>' (typically json ascii)
+```
 
 Internal API
 ------------
@@ -195,16 +205,18 @@ Internal API
 This APIs will absolutely change before they are made public
 (at the very least the leading `_` will be removed)
 
-* `OAUTH3.jwt`
-  * `OAUTH3.jwt.freshness(tokenMeta, staletimeSeconds, _now);             // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl)
+```
+OAUTH3.jwt
+  .freshness(tokenMeta, staletimeSeconds, _now);        // returns 'fresh', 'stale', or 'expired' (by seconds before expiry / ttl)
 
-* `OAUTH3.utils`
-  * `OAUTH3.utils.url._normalizePath('oauth3.org/connect/');              // 'oauth3.org/connect'`
-  * `OAUTH3.utils._urlSafeBase64ToBase64(b64);                            // makes base64 safe for window.atob`
-  * `OAUTH3.utils.randomState();                                          // a 128-bit crypto-random string`
-  * `OAUTH3.utils._insecureRandomState();                                 // a fallback for randomState() in old browsers`
+OAUTH3.utils
+  .url._normalizePath('oauth3.org/connect/');           // 'oauth3.org/connect'
+  ._urlSafeBase64ToBase64(b64);                         // makes base64 safe for window.atob
+  .randomState();                                       // a 128-bit crypto-random string
+  ._insecureRandomState();                              // a fallback for randomState() in old browsers
 
-* `OAUTH3._browser` a collection of things a browser needs to perform requests
+OAUTH3._browser                                         // a collection of things a browser needs to perform requests
+```
 
 Roadmap
 -------