Include class relationship diagrams in network stack documentation.

net/docs/life-of-a-url-request.md

Index: net/docs/life-of-a-url-request.md
diff --git a/net/docs/life-of-a-url-request.md b/net/docs/life-of-a-url-request.md
index 63f55f698bc86cad278b4d585d866a141d423aaa..f3ff1c6c69c689acefc0785e2c381b2daed605c2 100644
--- a/net/docs/life-of-a-url-request.md
+++ b/net/docs/life-of-a-url-request.md
@@ -293,6 +293,24 @@ Either way, the ClientSocketHandle returns the socket is then returned to the
 socket pool, either for reuse or so the socket pool knows it has another free
 socket slot.
 
+### Object Relationships and Ownership
+
+A sample of the object relationships involved in the above process is
+diagramed here: 
+
+![Object Relationship Diagram for URLRequest lifetime](url_request.svg)
+
+There are a couple of points in the above diagram that do not come
+clear visually:
+
+* The method that generates the filter chain that is hung off the
+  URLRequestJob is declared on URLRequestJob, but the only current
+  implementation of it is on URLRequestHttpJob, so the generation is
+  shown as happening from that class.
+* HttpTransactions of different types are layered; i.e. a
+  HttpCache::Transaction contains a pointer to an HttpTransaction, but
+  that pointed-to HttpTransaction generally is an
+  HttpNetworkTransaction. 
 
 # Additional Topics
 
@@ -418,6 +436,33 @@ pool, they must have their own distinct group name. This is needed so that, for
 instance, SSL and HTTP connections won't be grouped together in the
 TcpClientSocketPool, which the SSLClientSocketPool sits on top of.
 
+### Socket Pool Class Relationships
+
+The relationships between the important classes in the socket pools is
+shown diagramatically for the lowest layer socket pool

[eroman, 2016/04/04 21:29:18]

spelling: diagrammatically

as an aside, I initially read that as "dramatically" and was getting all excited
for what followed. but then i realized my error and the magic moment was gone.

[Randy Smith (Not in Mondays), 2016/04/04 21:44:50]

Done.
Sorry for the let-down.  I suspect it's a consistent feature of reviewing my
code :-}.

+(TransportSocketPool) below. 
+
+![Object Relationship Diagram for Socket Pools](pools.svg)
+
+The ClientSocketPoolBase is a template class templatized on the class
+containing the parameters for the appropriate type of socket (in this
+case TransportSocketParams).  It contains a pointer to the
+ClientSocketPoolBaseHelper, which contains all the type-independent
+machinery of the socket pool.  
+
+When socket pools are initialized, they in term initialize their

[eroman, 2016/04/04 21:29:18]

should it be "in term" or "in turn"?
Asking because I genuinely don't know, but am more familiar with "in turn".

[Randy Smith (Not in Mondays), 2016/04/04 21:44:50]

Yup, it's "in turn".  I should have put more energy into the writing; it was an
afterthought once I got the diagrams in ok shape :-J.

+templatized ClientSocketPoolBase member with an object with which it
+should create connect jobs.  That object must drive from

[eroman, 2016/04/04 21:29:18]

"must drive" ?  must derive?

[Randy Smith (Not in Mondays), 2016/04/04 21:44:50]

Yep; fixed.

+ClientSocketPoolBase::ConnectJobFactory templatized by the same type
+as the ClientSocketPoolBase.  (In the case of the diagram above, that
+object is a TransportConnectJobFactory, which derives from
+ClientSocketPoolBase::ConnectJobFactory<TransportSocketParams>.)
+Internally, that object is wrapped in a type-unsafe wrapper
+(ClientSocketPoolBase::ConnectJobFactoryAdaptor) so that it can be
+passed to the initialization of the ClientSocketPoolBaseHelper.  This
+allows the helper to create connect jobs while preserving a type-safe
+API to the initialization of the socket pool.

[eroman, 2016/04/04 21:29:18]

and for the reader's head to explode :)

[Randy Smith (Not in Mondays), 2016/04/04 21:44:50]

Ah, comprehension has been achieved! :-}

Backing up a sec, this is very much one of the things I want you to review.  I
started out with pretty pictures I created for my own understanding of some
particular problem I was chasing at the time, and am now trying to make those
useful for other folks.  But that doesn't mean the pictures (or the picture
description) is actually useful; we might be better off just not having the
socket pool stuff I've put together in the code base.  I think if you need to do
any work *inside* socket pools, the complicated derivation and relationship
structure is important to understand, but if you just need to understand the
interface, it's probably better not to know.  And even in the first case, I
don't know if I provide *enough* information to be useful; I haven't gone into
any of the gotchas involved in our complex layering (mostly because I don't
understand them, I just know they're there).

So: Should the above paragraph and it's related picture be in the docs, or are
we better off without?

[eroman, 2016/04/06 17:41:17]

We are better off with the docs IMO. Thanks!

It risks becoming stale, but let's see how it works :)

+
 ### SSL
 
 When an SSL connection is needed, the ClientSocketPoolManager assembles the