Documentation missing for agent option

[thomas-riccardi]

request accepts a http/https Agent as agent option, but it's not documented.
What is documented is how to pass a pool of agents as pool option, but the code first checks if self.agent exists before using self.pool to get the http agent:

request/request.js

Lines 486 to 490 in 2ca0633

	if (self.pool === false) {
	self.agent = false
	} else {
	self.agent = self.agent || self.getNewAgent()
	}

This should be documented & tested, or it should be removed... Otherwise we cannot rely on it.

[simov]

I agree there are other options missing from the docs as well, like agentClass and agentOptions mentioned here #1637

[simov]

@triccardi-systran see #1671

[tvdstaaij]

It sure seems to work, I just passed in a https.Agent object with the keepAlive option set to true (Node 0.12) and verified using an external TCP analysis tool that the connections are kept alive and reused, while this is not the case when the custom agent is not passed in.

This is a very useful feature but it took me over an hour of googling and analyzing source code to find it, so seconding the documentation request. I also suggest updating the documentation for pool so that the differences and use cases for the two are made clear.