Skip to content

Commit

Permalink
doc: http: add cross-links for easier clicking
Browse files Browse the repository at this point in the history
Make it a little easier to navigate the http module documentation by
turning class names and methods into links to the appropriate section.
  • Loading branch information
bnoordhuis committed Oct 16, 2013
1 parent 9a3a0cc commit 5ef03bc
Showing 1 changed file with 33 additions and 24 deletions.
57 changes: 33 additions & 24 deletions doc/api/http.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ This is an [EventEmitter][] with the following events:

Emitted each time there is a request. Note that there may be multiple requests
per connection (in the case of keep-alive connections).
`request` is an instance of `http.IncomingMessage` and `response` is
an instance of `http.ServerResponse`
`request` is an instance of [http.IncomingMessage][] and `response` is
an instance of [http.ServerResponse][].

### Event: 'connection'

Expand All @@ -83,7 +83,7 @@ Emitted each time a request with an http Expect: 100-continue is received.
If this event isn't listened for, the server will automatically respond
with a 100 Continue as appropriate.

Handling this event involves calling `response.writeContinue` if the client
Handling this event involves calling [response.writeContinue()][] if the client
should continue to send the request body, or generating an appropriate HTTP
response (e.g., 400 Bad Request) if the client should not continue to send the
request body.
Expand Down Expand Up @@ -233,7 +233,7 @@ The response implements the [Writable Stream][] interface. This is an
`function () { }`

Indicates that the underlying connection was terminated before
`response.end()` was called or able to flush.
[response.end()][] was called or able to flush.

### response.writeContinue()

Expand All @@ -255,9 +255,9 @@ Example:
'Content-Type': 'text/plain' });

This method must only be called once on a message and it must
be called before `response.end()` is called.
be called before [response.end()][] is called.

If you call `response.write()` or `response.end()` before calling this, the
If you call [response.write()][] or [response.end()][] before calling this, the
implicit/mutable headers will be calculated and call this function for you.

Note: that Content-Length is given in bytes not characters. The above example
Expand All @@ -284,9 +284,9 @@ sockets.

### response.statusCode

When using implicit headers (not calling `response.writeHead()` explicitly), this property
controls the status code that will be sent to the client when the headers get
flushed.
When using implicit headers (not calling [response.writeHead()][] explicitly),
this property controls the status code that will be sent to the client when
the headers get flushed.

Example:

Expand Down Expand Up @@ -342,8 +342,8 @@ Example:

### response.write(chunk, [encoding])

If this method is called and `response.writeHead()` has not been called, it will
switch to implicit header mode and flush the implicit headers.
If this method is called and [response.writeHead()][] has not been called,
it will switch to implicit header mode and flush the implicit headers.

This sends a chunk of the response body. This method may
be called multiple times to provide successive parts of the body.
Expand Down Expand Up @@ -424,7 +424,7 @@ Options:
- `false`: opts out of connection pooling with an Agent, defaults request to
`Connection: close`.

`http.request()` returns an instance of the `http.ClientRequest`
`http.request()` returns an instance of the [http.ClientRequest][]
class. The `ClientRequest` instance is a writable stream. If one needs to
upload a file with a POST request, then write to the `ClientRequest` object.

Expand Down Expand Up @@ -556,7 +556,7 @@ data chunk or when closing the connection.
To get the response, add a listener for `'response'` to the request object.
`'response'` will be emitted from the request object when the response
headers have been received. The `'response'` event is executed with one
argument which is an instance of `http.IncomingMessage`.
argument which is an instance of [http.IncomingMessage][].

During the `'response'` event, one can add listeners to the
response object; particularly to listen for the `'data'` event.
Expand All @@ -581,7 +581,7 @@ The request implements the [Writable Stream][] interface. This is an
`function (response) { }`

Emitted when a response is received to this request. This event is emitted only
once. The `response` argument will be an instance of `http.IncomingMessage`.
once. The `response` argument will be an instance of [http.IncomingMessage][].

Options:

Expand Down Expand Up @@ -760,9 +760,10 @@ Once a socket is assigned to this request and is connected

## http.IncomingMessage

An `IncomingMessage` object is created by `http.Server` or `http.ClientRequest`
and passed as the first argument to the `'request'` and `'response'` event
respectively. It may be used to access response status, headers and data.
An `IncomingMessage` object is created by [http.Server][] or
[http.ClientRequest][] and passed as the first argument to the `'request'`
and `'response'` event respectively. It may be used to access response status,
headers and data.

It implements the [Readable Stream][] interface, as well as the
following additional events, methods, and properties.
Expand Down Expand Up @@ -813,14 +814,14 @@ Calls `message.connection.setTimeout(msecs, callback)`.

### message.method

**Only valid for request obtained from `http.Server`.**
**Only valid for request obtained from [http.Server][].**

The request method as a string. Read only. Example:
`'GET'`, `'DELETE'`.

### message.url

**Only valid for request obtained from `http.Server`.**
**Only valid for request obtained from [http.Server][].**

Request URL string. This contains only the URL that is
present in the actual HTTP request. If the request is:
Expand Down Expand Up @@ -867,21 +868,29 @@ request.connection.getPeerCertificate() to obtain the client's
authentication details.


[Agent]: #http_class_http_agent
['checkContinue']: #http_event_checkcontinue
['listening']: net.html#net_event_listening
[Agent]: #http_class_http_agent
[Buffer]: buffer.html#buffer_buffer
[EventEmitter]: events.html#events_class_events_eventemitter
[Readable Stream]: stream.html#stream_readable_stream
[Writable Stream]: stream.html#stream_writable_stream
[global Agent]: #http_http_globalagent
[http.ClientRequest]: #http_class_http_clientrequest
[http.IncomingMessage]: #http_http_incomingmessage
[http.ServerResponse]: #http_class_http_serverresponse
[http.Server]: #http_class_http_server
[http.request()]: #http_http_request_options_callback
[http.request()]: #http_http_request_options_callback
[http.IncomingMessage]: #http_class_http_incomingmessage
['listening']: net.html#net_event_listening
[net.Server.close()]: net.html#net_server_close_callback
[net.Server.listen(path)]: net.html#net_server_listen_path_callback
[net.Server.listen(port)]: net.html#net_server_listen_port_host_backlog_callback
[Readable Stream]: stream.html#stream_readable_stream
[response.end()]: #http_response_end_data_encoding
[response.write()]: #http_response_write_chunk_encoding
[response.writeContinue()]: #http_response_writecontinue
[response.writeHead()]: #http_response_writehead_statuscode_reasonphrase_headers
[socket.setKeepAlive()]: net.html#net_socket_setkeepalive_enable_initialdelay
[socket.setNoDelay()]: net.html#net_socket_setnodelay_nodelay
[socket.setTimeout()]: net.html#net_socket_settimeout_timeout_callback
[stream.setEncoding()]: stream.html#stream_stream_setencoding_encoding
[url.parse()]: url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost
[Writable Stream]: stream.html#stream_writable_stream

0 comments on commit 5ef03bc

Please sign in to comment.