Formatting net documentation.

docs/api/net.md

@@ -2,52 +2,52 @@
 
 > Issue HTTP/HTTPS requests.
 
-The `net` module is a client-side API for issuing HTTP(S) requests. It is similar to the 
-[HTTP](https://nodejs.org/api/http.html)  and [HTTPS](https://nodejs.org/api/https.html) modules of Node.js 
-but it uses Chromium native networking library instead of the Node.js implementation offering 
-therefore a much greater support regarding web proxies.
-
-Following is a non-exhaustive list of why you may consider using the `net` module instead of the native Node.js modules:
-* Automatic management of system proxy configuration, support of the wpad protocol and proxy pac configuration files.
+The `net` module is a client-side API for issuing HTTP(S) requests. It is
+similar to the  [HTTP](https://nodejs.org/api/http.html)  and
+[HTTPS](https://nodejs.org/api/https.html) modules of Node.js but it uses
+Chromium native networking library instead of the Node.js implementation
+offering therefore a much greater support regarding web proxies.
+
+Following is a non-exhaustive list of why you may consider using the `net`
+module instead of the native Node.js modules:
+* Automatic management of system proxy configuration, support of the wpad
+protocol and proxy pac configuration files.
 * Automatic tunneling of HTTPS requests.
-* Support for authenticating proxies using basic, digest, NTLM, Kerberos or negotiate authentication schemes.
-* Support for traffic monitoring proxies: Fiddler-like proxies used for access control and monitoring.
+* Support for authenticating proxies using basic, digest, NTLM, Kerberos or
+negotiate authentication schemes.
+* Support for traffic monitoring proxies: Fiddler-like proxies used for access
+control and monitoring.
 
-The `net` module API has been specifically designed to mimic, as much closely as possible, the familiar Node.js API.
-The API components including classes, methods, properties and event names are similar to those commonly used in Node.js.
+The `net` module API has been specifically designed to mimic, as much closely as
+possible, the familiar Node.js API. The API components including classes,
+methods, properties and event names are similar to those commonly used in
+Node.js.
 
-For instance, the following example quickly shows how the `net` API might be used:
+For instance, the following example quickly shows how the `net` API might be
+used:
 
 ```javascript
 const {app} = require('electron')
-
 app.on('ready', () => {
-  
   const {net} = require('electron')
-
   const request = net.request('https://github.com')
-
   request.on('response', (response) => {
-
     console.log(`STATUS: ${response.statusCode}`);  
     console.log(`HEADERS: ${JSON.stringify(response.headers)}`);
-
     response.on('data', (chunk) => {
       console.log(`BODY: ${chunk}`)
     })
-
     response.on('end', () => {
       console.log('No more data in response.');
     })
-
   })
-
   request.end()
 })
 ```
 
-By the way, it is almost identical to the way you would normally use the
-[HTTP](https://nodejs.org/api/http.html)/[HTTPS](https://nodejs.org/api/https.html) modules of Node.js
+By the way, it is almost identical to how you would normally use the
+[HTTP](https://nodejs.org/api/http.html)/[HTTPS](https://nodejs.org/api/https.html)
+modules of Node.js
 
 ## Methods
 
@@ -59,29 +59,37 @@ The `net` module has the following methods:
 
 Returns `ClientRequest`
 
-Create a `ClientRequest` instance using the provided `options` object which is directly
-passed to the `ClientRequest` constructor. The `net.request` method would be used to issue
-both secure and insecure HTTP requests according to the specified protocol scheme in the `options` object.
+Creates a `ClientRequest` instance using the provided `options` which are
+directly forwarded to the `ClientRequest` constructor. The `net.request` method
+would be used to issue both secure and insecure HTTP requests according to the
+specified protocol scheme in the `options` object.
 
 ## Class: ClientRequest
 
-`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams) interface
-and it is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
+`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
+interface and it is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
 
 ### `new ClientRequest(options)`
 
-* `options` Object or String - If `options` is a String, it is interpreted as the request URL. 
-If it is an object, it is expected to fully specify an HTTP request via the following properties:
-  * `method` String (optional) - The HTTP request method. Defaults to the GET method.
-  * `url` String (required) - The request URL. Must be provided in the absolute form with the protocol scheme specified as http or https.
-  * `protocol` String (optional) - The protocol scheme in the form 'scheme:'. Current supported values are 'http:' or 'https:'. Defaults to 'http:'.
-  * `host` String (optional) - The server host provided as a concatenation of a hostname and a port number 'hostname:port'
+* `options` Object or String - If `options` is a String, it is interpreted as
+the request URL. 
+If it is an object, it is expected to fully specify an HTTP request via the
+following properties:
+  * `method` String (optional) - The HTTP request method. Defaults to the GET
+method.
+  * `url` String (optional) - The request URL. Must be provided in the absolute
+form with the protocol scheme specified as http or https.
+  * `protocol` String (optional) - The protocol scheme in the form 'scheme:'.
+Currently supported values are 'http:' or 'https:'. Defaults to 'http:'.
+  * `host` String (optional) - The server host provided as a concatenation of
+the hostname and the port number 'hostname:port'
   * `hostname` String (optional) - The server host name.
   * `port` Integer (optional) - The server's listening port number.
   * `path` String (optional) - The path part of the request URL. 
   
-`options` properties `protocol`, `host`, `hostname`, `port` and `path` strictly 
-follow the Node.js model as described in the [URL](https://nodejs.org/api/url.html) module.
+`options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
+strictly follow the Node.js model as described in the
+[URL](https://nodejs.org/api/url.html) module.
 
 For instance, we could have created the same request to 'github.com' as follows:
 
@@ -101,7 +109,7 @@ const request = net.request({
 
 Returns:
 
-* `response` IncomingMessage - An object representing an HTTP response message.
+* `response` IncomingMessage - An object representing the HTTP response message.
 
 #### Event: 'login'
 
@@ -127,7 +135,8 @@ request.on('login', (authInfo, callback) => {
   callback('username', 'password')
 })
 ```
-Providing empty credentials will cancel the request and report an authentication error on the response object:
+Providing empty credentials will cancel the request and report an authentication
+error on the response object:
 
 ```JavaScript
 request.on('response', (response) => {
@@ -143,11 +152,13 @@ request.on('login', (authInfo, callback) => {
 
 #### Event: 'finish'
 
-Emitted just after the last chunk of the `request`'s data has been written into the `request` object.
+Emitted just after the last chunk of the `request`'s data has been written into
+the `request` object.
 
 #### Event: 'abort'
 
-Emitted when the `request` is aborted. The abort event will not be fired if the `request` is already closed.
+Emitted when the `request` is aborted. The `abort` event will not be fired if
+the `request` is already closed.
 
 #### Event: 'error'
 
@@ -155,36 +166,40 @@ Returns:
 
 * `error` Error - an error object providing some information about the failure.
 
-Emitted when the `net` module fails to issue a network request. Typically when the `request`
-object emits an error event, a close event will subsequently follow and no response object will be provided.
+Emitted when the `net` module fails to issue a network request. Typically when
+the `request` object emits an `error` event, a `close` event will subsequently
+follow and no response object will be provided.
 
 #### Event: 'close'
 
-Emitted as the last event in the HTTP request-response transaction. The close event indicates
-that no more events will be emitted on either the `request` or `response` objects.
+Emitted as the last event in the HTTP request-response transaction. The `close`
+event indicates that no more events will be emitted on either the `request` or
+`response` objects.
 
 ### Instance Properties
 
 #### `request.chunkedEncoding`
 
-A Boolean specifying whether the request will use HTTP chunked transfer encoding or
-not. Defaults to false. The property is readable and writable, 
-however it can be set only before the first write operation as the HTTP headers are
-not yet put on the wire. Trying to set the `chunkedEncoding` property
-after a write will throw an error.
+A Boolean specifying whether the request will use HTTP chunked transfer encoding
+or not. Defaults to false. The property is readable and writable, however it can
+be set only before the first write operation as the HTTP headers are not yet put
+on the wire. Trying to set the `chunkedEncoding` property after the first write
+will throw an error.
 
-Using chunked encoding is strongly recommended if you need to send a large request body as
-data will be streamed as small chunks instead of being internally buffered 
-in Electron memory.
+Using chunked encoding is strongly recommended if you need to send a large
+request body as data will be streamed in small chunks instead of being
+internally buffered inside Electron process memory.
 
 ### Instance Methods
 
 #### `request.setHeader(name, value)`
 
-* `name` String - An extra header name.
-* `value` String - An extra header value.
+* `name` String - An extra HTTP header name.
+* `value` String - An extra HTTP header value.
 
-Adds an extra HTTP header. The header name will issued as it is without lowercasing.
+Adds an extra HTTP header. The header name will issued as it is without
+lowercasing. It can be called only before first write. Calling this method after
+the first write will throw an error.
 
 #### `request.getHeader(name)`
 
@@ -196,17 +211,20 @@ Returns String - The value of a previously set extra header name.
 
 * `name` String - Specify an extra header name.
 
-Removes a previously set extra header name. 
+Removes a previously set extra header name. This method can be called only
+before first write. Trying to call it after the first write will throw an error.
 
 #### `request.write(chunk[, encoding][, callback])`
 
-* `chunk` String or Buffer - A chunk of the request body' data. If it is a string,
-it is converted into a Buffer object using the specified encoding.
-* `encoding` String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'.
+* `chunk` String or Buffer - A chunk of the request body's data. If it is a
+string, it is converted into a Buffer using the specified encoding.
+* `encoding` String (optional) - Used to convert string chunks into Buffer
+objects. Defaults to 'utf-8'.
 * `callback` Function (optional) - Called after the write operation ends.
 
-Adds a chunk of data to the request body. Generally, the first write operation causes the request headers to be issued on the wire. 
-After the first write operation, it is not allowed to add or remove a custom header.
+Adds a chunk of data to the request body. The first write operation may cause
+the request headers to be issued on the wire. After the first write operation,
+it is not allowed to add or remove a custom header.
 
 #### `request.end([chunk][, encoding][, callback])`
 
@@ -214,21 +232,22 @@ After the first write operation, it is not allowed to add or remove a custom hea
 * `encoding` String (optional)
 * `callback` Function (optional)
 
-Sends the last chunk of the request data. Subsequent write or end operations will not
-be allowed. The finish event is emitted just after the end operation.
+Sends the last chunk of the request data. Subsequent write or end operations
+will not be allowed. The `finish` event is emitted just after the end operation.
 
 #### `request.abort()`
 
-Cancels an ongoing HTTP transaction. If the request has already closed, the abort operation will have no effect. 
-Otherwise an ongoing event will emit abort and close events. Additionally, if there is an ongoing response object,
-it will emit the aborted event.
+Cancels an ongoing HTTP transaction. If the request has already emitted the
+`close` event, the abort operation will have no effect. Otherwise an ongoing
+event will emit `abort` and `close` events. Additionally, if there is an ongoing
+response object,it will emit the `aborted` event.
 
 
 ## Class: IncomingMessage
 
 `IncomingMessage` represents an HTTP response message.
-It is a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) and therefore 
-an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
+It is a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)
+and consequently an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
 
 ### Instance Events
 
@@ -238,7 +257,8 @@ Returns:
 
 * `chunk`: Buffer - A chunk of response body's data.
 
-The data event is the usual method of transferring response data into applicative code. 
+The `data` event is the usual method of transferring response data into
+applicative code. 
 
 #### Event 'end'
 
@@ -250,13 +270,14 @@ Emitted when a request has been canceled during an ongoing HTTP transaction.
 
 #### Event 'error'
 
-Returns
+Returns:
 
 `error` Error - Typically holds an error string identifying failure root cause.
 
-Emitted if an error is encountered while streaming response data events. For instance, 
-if the server closes the underlying socket while streaming the response, an error event 
-will be emitted on the response object and a close event will subsequently follow in the request object.
+Emitted when an error was encountered while streaming response data events. For
+instance, if the server closes the underlying while the response is still
+streaming, an `error` event will be emitted on the response object and a `close`
+event will subsequently follow on the request object.
 
 ### Instance properties
 
@@ -272,7 +293,8 @@ A String representing the HTTP status message.
 
 #### `response.headers`
 
-An Object representing the response HTTP headers. The `headers` object is formatted as follows:
+An Object representing the response HTTP headers. The `headers` object is
+formatted as follows:
 
 * All header names are lowercased.
 * Each header name produces an array-valued property on the headers object.
@@ -280,8 +302,10 @@ An Object representing the response HTTP headers. The `headers` object is format
 
 #### `response.httpVersion`
 
-A String indicating the HTTP protocol version number. Typical values are '1.0' or '1.1'. Additionally `httpVersionMajor` and
-`httpVersionMinor` are two Integer-valued readable properties that return respectively the HTTP major and minor version numbers.
+A String indicating the HTTP protocol version number. Typical values are '1.0'
+or '1.1'. Additionally `httpVersionMajor` and `httpVersionMinor` are two
+Integer-valued readable properties that return respectively the HTTP major and
+minor version numbers.