docs: Revise the webRequest and protocol docs

docs/api/protocol.md

@@ -54,6 +54,19 @@ going to be created with `scheme`. `completion` will be called with
 `completion(null)` when `scheme` is successfully registered or
 `completion(error)` when failed.
 
+* `request` Object
+  * `url` String
+  * `referrer` String
+  * `method` String
+  * `uploadData` Array (optional)
+* `callback` Function
+
+The `uploadData` is an array of `data` objects:
+
+* `data` Object
+  * `bytes` Buffer - Content being sent.
+  * `file` String - Path of file being uploaded.
+
 To handle the `request`, the `callback` should be called with either the file's
 path or an object that has a `path` property, e.g. `callback(filePath)` or
 `callback({path: filePath})`.
@@ -61,7 +74,7 @@ path or an object that has a `path` property, e.g. `callback(filePath)` or
 When `callback` is called with nothing, a number, or an object that has an
 `error` property, the `request` will fail with the `error` number you
 specified. For the available error numbers you can use, please see the
-[net error list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
+[net error list][net-error].
 
 By default the `scheme` is treated like `http:`, which is parsed differently
 than protocols that follow the "generic URI syntax" like `file:`, so you
@@ -74,9 +87,11 @@ treated as a standard scheme.
 * `handler` Function
 * `completion` Function (optional)
 
-Registers a protocol of `scheme` that will send a `Buffer` as a response. The
+Registers a protocol of `scheme` that will send a `Buffer` as a response.
-`callback` should be called with either a `Buffer` object or an object that
+
-has the `data`, `mimeType`, and `chart` properties.
+The usage is the same with `registerFileProtocol`, except that the `callback`
+should be called with either a `Buffer` object or an object that has the `data`,
+`mimeType`, and `charset` properties.
 
 Example:
 
@@ -95,9 +110,11 @@ protocol.registerBufferProtocol('atom', function(request, callback) {
 * `handler` Function
 * `completion` Function (optional)
 
-Registers a protocol of `scheme` that will send a `String` as a response. The
+Registers a protocol of `scheme` that will send a `String` as a response.
-`callback` should be called with either a `String` or an object that has the
+
-`data`, `mimeType`, and `chart` properties.
+The usage is the same with `registerFileProtocol`, except that the `callback`
+should be called with either a `String` or an object that has the `data`,
+`mimeType`, and `charset` properties.
 
 ### `protocol.registerHttpProtocol(scheme, handler[, completion])`
 
@@ -106,16 +123,25 @@ Registers a protocol of `scheme` that will send a `String` as a response. The
 * `completion` Function (optional)
 
 Registers a protocol of `scheme` that will send an HTTP request as a response.
-The `callback` should be called with an object that has the `url`, `method`,
+
+The usage is the same with `registerFileProtocol`, except that the `callback`
+should be called with a `redirectRequest` object that has the `url`, `method`,
 `referrer`, `uploadData` and `session` properties.
 
+* `redirectRequest` Object
+  * `url` String
+  * `method` String
+  * `session` Object (optional)
+  * `uploadData` Object
+
 By default the HTTP request will reuse the current session. If you want the
 request to have a different session you should set `session` to `null`.
 
-POST request should provide an `uploadData` object.
+For POST requests the `uploadData` object must be provided.
+
 * `uploadData` object
   * `contentType` String - MIME type of the content.
-  *  `data` String - Content to be sent.
+  * `data` String - Content to be sent.
 
 ### `protocol.unregisterProtocol(scheme[, completion])`
 
@@ -174,3 +200,5 @@ which sends a new HTTP request as a response.
 * `completion` Function
 
 Remove the interceptor installed for `scheme` and restore its original handler.
+
+[net-error]: https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h

docs/api/session.md

@@ -333,8 +333,13 @@ is about to occur.
   * `resourceType` String
   * `timestamp` Double
   * `uploadData` Array (optional)
-    * `bytes` Buffer - Content being sent.
+* `callback` Function
-    * `file` String - Path of file being uploaded.
+
+The `uploadData` is an array of `data` objects:
+
+* `data` Object
+  * `bytes` Buffer - Content being sent.
+  * `file` String - Path of file being uploaded.
 
 The `callback` has to be called with an `response` object:
 
@@ -359,6 +364,7 @@ TCP connection is made to the server, but before any http data is sent.
   * `resourceType` String
   * `timestamp` Double
   * `requestHeaders` Object
+* `callback` Function
 
 The `callback` has to be called with an `response` object:
 
@@ -401,6 +407,7 @@ response headers of a request have been received.
   * `statusLine` String
   * `statusCode` Integer
   * `responseHeaders` Object
+* `callback` Function
 
 The `callback` has to be called with an `response` object: