Changes to http.md

[fhalde]

Change KeepAlive to keepAlive
Ref #10567

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[mscdex]

The HTTP 1.1 RFC actually uses 'Keep-Alive' when referring to the mechanism/functionality in general. I think it would be better to align with the RFC instead.

[Trott]

For the instances that refer to the flag, keepAlive is right, but use backticks too:

`keepAlive`

That will render like this: keepAlive

For instances that don't refer to the flag but instead refer to HTTP Keep-Alive: Keep-Alive is probably the way to go.

/cc @nodejs/documentation

[fhalde]

@Trott @mscdex everything seems to refer to HTTP Keep-Alive to me 😕
Maybe I should let the one who raised the issue handle this.

[lance]

In the HTTP 1.1 RFC it seems that HTTP Keep-Alive is the mechanism, and Connection: keep-alive is the request header, and in Node, the Agent constructor option is { keepAlive: <boolean>}. There are a few different areas where I think all of this could be clarified. For example:

If you opt into using HTTP KeepAlive, you can create an Agent object with that flag set to true.

Should probably read more like:

If you opt into using HTTP Keep-Alive, you can create an Agent instance, providing { keepAlive: true } among the constructor options.

@fhalde, although I'm not the one who raised the issue initially, I'd be happy to take this on if you're disinclined.

[fhalde]

@lance go ahead dude 😄

[yorkie]

By the way, the Agent seems to be:

1. agent in lowercase
2. Agent with backticks

[lance]

@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?

[lance]

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.

[mscdex]

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

[lance]

I am going to close this in favor of #10715. If that's not the best way to go about it, someone please let me know. :)