docs: improvement fs, http and https

doc/api/fs.markdown

@@ -133,7 +133,7 @@ Synchronous lchmod(2).
 ### fs.stat(path, [callback])
 
 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
-`stats` is a [`fs.Stats`](#fs.Stats) object.  See the [fs.Stats](#fs.Stats)
+`stats` is a [fs.Stats](#fs.Stats) object.  See the [fs.Stats](#fs.Stats)
 section below for more information.
 
 ### fs.lstat(path, [callback])
@@ -471,9 +471,9 @@ similar to this:
       ctime: Mon, 10 Oct 2011 23:24:11 GMT }
 
 Please note that `atime`, `mtime` and `ctime` are instances
-of [`Date`][MDN-Date] object and to compare the values of
+of [Date][MDN-Date] object and to compare the values of
 these objects you should use appropriate methods. For most
-general uses [`getTime()`][MDN-Date-getTime] will return
+general uses [getTime()][MDN-Date-getTime] will return
 the number of milliseconds elapsed since _1 January 1970
 00:00:00 UTC_ and this integer should be sufficient for
 any comparison, however there additional methods which can

doc/api/http.markdown

@@ -387,28 +387,29 @@ followed by `response.end()`.
 ## http.request(options, callback)
 
 Node maintains several connections per server to make HTTP requests.
-This function allows one to transparently issue requests.  Options align
+This function allows one to transparently issue requests.  `options` align
-with `url.parse`.
+with [url.parse()](url.html#url.parse).
 
 Options:
 
 - `host`: A domain name or IP address of the server to issue the request to.
-- `hostname`: To support `url.parse` `hostname` is prefered over
+  Defaults to `'localhost'`.
-  `host`
+- `hostname`: To support `url.parse()` `hostname` is prefered over `host`
-- `port`: Port of remote server.
+- `port`: Port of remote server. Defaults to 80.
 - `socketPath`: Unix Domain Socket (use one of host:port or socketPath)
-- `method`: A string specifying the HTTP request method. Possible values:
+- `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
-  `'GET'` (default), `'POST'`, `'PUT'`, and `'DELETE'`.
+- `path`: Request path. Defaults to `'/'`. Should include query string if any.
-- `path`: Request path. Should include query string and fragments if any.
+  E.G. `'/index.html?page=12'`
-   E.G. `'/index.html?page=12'`
 - `headers`: An object containing request headers.
 - `auth`: Basic authentication i.e. `'user:password'` to compute an
   Authorization header.
-- `agent`: Controls `Agent` behavior. When an Agent is used request will default to 
+- `agent`: Controls [Agent](#http.Agent) behavior. When an Agent is used
-   Connection:keep-alive. Possible values:
+  request will default to `Connection: keep-alive`. Possible values:
- - `undefined` (default): use default `Agent` for this host and port.
+ - `undefined` (default): use [global Agent](#http.globalAgent) for this host
+   and port.
  - `Agent` object: explicitly use the passed in `Agent`.
- - `false`: opts out of connection pooling with an Agent, defaults request to Connection:close.
+ - `false`: opts out of connection pooling with an Agent, defaults request to
+   `Connection: close`.
 
 `http.request()` returns an instance of the `http.ClientRequest`
 class. The `ClientRequest` instance is a writable stream. If one needs to

doc/api/https.markdown

@@ -34,7 +34,7 @@ Example:
 ## https.request(options, callback)
 
 Makes a request to a secure web server.
-All options from [`http.request()`](http.html#http.request) are valid.
+All options from [http.request()](http.html#http.request) are valid.
 
 Example:
 
@@ -68,12 +68,30 @@ The options argument has the following options
 - path: Path to request. Default `'/'`.
 - method: HTTP request method. Default `'GET'`.
 
-The following options can also be specified.
+- `host`: A domain name or IP address of the server to issue the request to.
-However, a global [Agent](http.html#http.Agent) cannot be used.
+  Defaults to `'localhost'`.
+- `hostname`: To support `url.parse()` `hostname` is prefered over `host`
+- `port`: Port of remote server. Defaults to 443.
+- `method`: A string specifying the HTTP request method. Defaults to `'GET'`.
+- `path`: Request path. Defaults to `'/'`. Should include query string if any.
+  E.G. `'/index.html?page=12'`
+- `headers`: An object containing request headers.
+- `auth`: Basic authentication i.e. `'user:password'` to compute an
+  Authorization header.
+- `agent`: Controls [Agent](#https.Agent) behavior. When an Agent is
+  used request will default to `Connection: keep-alive`. Possible values:
+ - `undefined` (default): use [globalAgent](#https.globalAgent) for this
+   host and port.
+ - `Agent` object: explicitly use the passed in `Agent`.
+ - `false`: opts out of connection pooling with an Agent, defaults request to
+   `Connection: close`.
 
-- key: Private key to use for SSL. Default `null`.
+The following options from [tls.connect()](tls.html#tls.connect) can also be
-- cert: Public x509 certificate to use. Default `null`.
+specified. However, a [globalAgent](#https.globalAgent) silently ignores these.
-- ca: An authority certificate or array of authority certificates to check
+
+- `key`: Private key to use for SSL. Default `null`.
+- `cert`: Public x509 certificate to use. Default `null`.
+- `ca`: An authority certificate or array of authority certificates to check
   the remote host against.
 
 In order to specify these options, use a custom `Agent`.
@@ -133,5 +151,13 @@ Example:
     });
 
 
+## https.Agent
+
+An Agent object for HTTPS similer to [http.Agent](http.html#http.Agent).
+See [https.request()](#https.request) for more information.
 
 
+## https.globalAgent
+
+Global instance of [https.Agent](#https.Agent) which is used as the default
+for all HTTPS client requests.

doc/api/tls.markdown

@@ -27,7 +27,7 @@ Alternatively you can send the CSR to a Certificate Authority for signing.
 `test/fixtures/keys/Makefile` in the Node source code)
 
 
-#### tls.createServer(options, secureConnectionListener)
+#### tls.createServer(options, [secureConnectionListener])
 
 Creates a new [tls.Server](#tls.Server).
 The `connectionListener` argument is automatically set as a listener for the
@@ -100,7 +100,7 @@ You can test this server by connecting to it with `openssl s_client`:
     openssl s_client -connect 127.0.0.1:8000
 
 
-#### tls.connect(port, [host], [options], secureConnectListener)
+#### tls.connect(port, [host], [options], [secureConnectListener])
 
 Creates a new client connection to the given `port` and `host`. (If `host`
 defaults to `localhost`.) `options` should be an object which specifies