Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Changes to http.md #10614

Closed
wants to merge 1 commit into from
Closed

Changes to http.md #10614

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions doc/api/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,13 @@ The HTTP Agent also defaults client requests to using
socket to become free the socket is closed. This means that Node.js's
pool has the benefit of keep-alive when under load but still does not
require developers to manually close the HTTP clients using
KeepAlive.
keepAlive.

If you opt into using HTTP KeepAlive, you can create an Agent object
If you opt into using HTTP keepAlive, you can create an Agent object
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By the way, the Agent seems to be:

  1. agent in lowercase
  2. Agent with backticks

Copy link
Member

@lance lance Jan 9, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@yorkie I agree that there are some inconsistencies with Agent as well. Most of the time when we see capital-A, 'Agent' it's directly preceded by "HTTP". As in

The HTTP Agent is used for pooling sockets used in HTTP client requests.

When referred to this way, it seems like it should be referring to "http.Agent" (as code, and scoped to the module), instead of "HTTP Agent" (as a non-standard English language description of the object itself). What do you think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess a follow on question would be whether we should always scope the object name, so that whenever Agent appears in backticks, it is written as http.Agent.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lance I think that's typically only done if you were referencing a module other than the one the current documentation is for.

with that flag set to `true`. (See the [constructor options][].)
Then, the Agent will keep unused sockets in a pool for later use. They
will be explicitly marked so as to not keep the Node.js process running.
However, it is still a good idea to explicitly [`destroy()`][] KeepAlive
However, it is still a good idea to explicitly [`destroy()`][] keepAlive
agents when they are no longer in use, so that the Sockets will be shut
down.

Expand Down Expand Up @@ -102,8 +102,8 @@ added: v0.3.4
Can have the following fields:
* `keepAlive` {Boolean} Keep sockets around in a pool to be used by
other requests in the future. Default = `false`
* `keepAliveMsecs` {Integer} When using HTTP KeepAlive, how often
to send TCP KeepAlive packets over sockets being kept alive.
* `keepAliveMsecs` {Integer} When using HTTP keepAlive, how often
to send TCP keepAlive packets over sockets being kept alive.
Default = `1000`. Only relevant if `keepAlive` is set to `true`.
* `maxSockets` {Number} Maximum number of sockets to allow per
host. Default = `Infinity`.
Expand Down Expand Up @@ -151,7 +151,7 @@ added: v0.11.4
Destroy any sockets that are currently in use by the agent.

It is usually not necessary to do this. However, if you are using an
agent with KeepAlive enabled, then it is best to explicitly shut down
agent with keepAlive enabled, then it is best to explicitly shut down
the agent when you know that it will no longer be used. Otherwise,
sockets may hang open for quite a long time before the server
terminates them.
Expand All @@ -164,7 +164,7 @@ added: v0.11.4
* {Object}

An object which contains arrays of sockets currently awaiting use by
the Agent when HTTP KeepAlive is used. Do not modify.
the Agent when HTTP keepAlive is used. Do not modify.

### agent.getName(options)
<!-- YAML
Expand All @@ -191,7 +191,7 @@ added: v0.11.7

* {Number}

By default set to 256. For Agents supporting HTTP KeepAlive, this
By default set to 256. For Agents supporting HTTP keepAlive, this
sets the maximum number of sockets that will be left open in the free
state.

Expand Down