Include class relationship diagrams in network stack documentation.

This CL includes class relationship diagrams for most of the
classes mentioned in life_of_a_url_request.md and a sketch of the
object relationships inside socket pools.  It also removes the net_docs
target (which wasn't really being used) and adds information for debugging
markdown changes and updating SVG files from dot source.

BUG=None
R=eroman@chromium.org
R=mmenke@chromium.org

Committed: https://crrev.com/fb2fd16bec430431971d14658ef3800b23f0ab3f
Cr-Commit-Position: refs/heads/master@{#385934}

Review URL: https://codereview.chromium.org/1859793002

Cr-Commit-Position: refs/heads/master@{#386113}

build/gn_migration.gypi

@@ -696,7 +696,6 @@
         ['OS=="linux" or OS=="win"', {
           'dependencies': [
             # TODO(GYP): Figure out which of these run on android/mac/win/ios/etc.
-            '../net/net.gyp:net_docs',
             '../remoting/remoting.gyp:ar_sample_test_driver',
 
             # TODO(GYP): in progress - see tfarina.
@@ -724,7 +723,6 @@
             '../content/content_shell_and_tests.gyp:content_shell_crash_service',
             '../gpu/gpu.gyp:angle_end2end_tests',
             '../gpu/gpu.gyp:angle_perftests',
-            '../net/net.gyp:net_docs',
             '../ppapi/ppapi_internal.gyp:ppapi_perftests',
             '../remoting/remoting.gyp:ar_sample_test_driver',
             '../remoting/remoting.gyp:remoting_breakpad_tester',

net/docs/README.txt

@@ -0,0 +1,20 @@
+To generate the output HTML from an input markdown file on Unix
+machines, execute the command:
+
+  PYTHONPATH=../../third_party python -m markdown -f <output>.html  <input>.md 
+
+On Windows machines, execute:
+
+  set PYTHONPATH=..\..\third_party
+  python -m markdown -f <output>.html <input>.md
+
+(This command line assumes that the net/docs directory is the current
+directory; if that's not the case, adjust the path to src/third_party
+to be accurate from whatever directory the command is executed from.)
+
+The diagrams included in the network stack documentation were
+generated with Graphviz, and both source (.dot) and output (.svg) are
+included in the repository.  If graphviz is installed, the output may
+be regenerated from the source via:
+
+  dot dot -Tsvg <name>.dot > <name>.svg

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 diagrammatically for the lowest layer socket pool
+(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 turn initialize their
+templatized ClientSocketPoolBase member with an object with which it
+should create connect jobs.  That object must derive from
+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.
+
 ### SSL
 
 When an SSL connection is needed, the ClientSocketPoolManager assembles the

net/docs/pools.dot

@@ -0,0 +1,101 @@
+digraph SocketPools {
+    subgraph cluster_legend {
+	label="Legend";
+
+	## The following legend is an attempt to match UML notation,
+	## except for template_class and Factory->object, which are
+	## invented for this diagram.
+	BaseClass;
+	SubClass [label="Derived Class"];
+	Whole;
+	Part;
+	A;
+	B;
+	Interface [label="Interface / ABC", style=dashed];
+	template_class [shape=diamond]; # Link will name parameter(s)
+
+	SubClass -> BaseClass [arrowhead="empty"];
+	SubClass -> Interface [arrowhead="empty", style=dashed];
+	Part -> Whole [arrowhead="diamond", label="ownership"];
+	Part -> Whole [arrowhead="odiamond", label="pointer"];
+	RefCountedPart -> Whole [arrowhead="diamond", color=red,
+		                 label="partial\nownership"];
+	A -> B [arrowhead="none", headlabel="?..?", taillabel="?..?",
+		label="association"];
+	// Often a "subgraph { rank=same; .. }" is used to wrap the
+	// below to make the generative relationship distinctive
+	// from the other class relationships.
+	Factory -> object [arrowhead=veevee];
+    };
+
+    ClientSocketPoolBase [shape=diamond];
+    ClientSocketPoolBaseHelper;
+
+    ClientSocketPoolBaseHelper_ConnectJobFactory
+        [style=dotted, label="ClientSocketPoolBaseHelper::\nConnectJobFactory"];
+    ClientSocketPoolBase_ConnectJobFactory
+        [style=dotted, shape=diamond,
+	 label="ClientSocketPoolBase::\nConnectJobFactory"];
+    ClientSocketPoolBase_ConnectJobFactoryAdaptor
+        [shape=diamond,
+	 label="ClientSocketPoolBase::\nConnectJobFactoryAdaptor"];
+
+    HigherLayeredPool [style=dotted];
+    LowerLayeredPool [style=dotted];
+    ClientSocketPool [style=dotted];
+
+    ConnectJob [style=dashed];
+    ConnectJob_Delegate [style=dotted, label="ConnectJob::Delegate"];
+
+    ClientSocketFactory [style=dotted];
+    DefaultClientSocketFactory;
+    TCPClientSocket;
+    StreamSocket [style=dotted]
+    Socket;
+
+    TransportSocketParams;
+    TransportConnectJobHelper;
+    TransportConnectJobFactory;
+    TransportConnectJob;
+
+    TransportClientSocketPool -> ClientSocketPool [arrowhead=empty];
+    ClientSocketPool -> LowerLayeredPool [arrowhead=empty];
+    ClientSocketPoolBaseHelper -> ConnectJob_Delegate [arrowhead=empty];
+    TransportConnectJobFactory -> ClientSocketPoolBase_ConnectJobFactory
+        [arrowhead=empty, label="TransportSocketParams"];
+    ClientSocketPoolBase_ConnectJobFactoryAdaptor ->
+        ClientSocketPoolBaseHelper_ConnectJobFactory
+ 	    [arrowhead=empty, arrowtail=none];
+    TransportConnectJob -> ConnectJob [arrowhead=empty];
+    DefaultClientSocketFactory -> ClientSocketFactory [arrowhead=empty];
+    StreamSocket -> Socket [arrowhead=empty]
+    TCPClientSocket -> StreamSocket [arrowhead=empty]
+
+    ClientSocketPoolBaseHelper -> ClientSocketPoolBase [arrowhead=diamond];
+    ClientSocketPoolBase -> TransportClientSocketPool
+        [arrowhead=diamond, label="TransportSocketParams"];
+    ClientSocketPoolBase_ConnectJobFactory ->
+        ClientSocketPoolBase_ConnectJobFactoryAdaptor [arrowhead=diamond];
+    ClientSocketPoolBaseHelper_ConnectJobFactory -> 
+        ClientSocketPoolBaseHelper [arrowhead=diamond];
+    TransportConnectJobHelper -> TransportConnectJob [arrowhead=diamond];
+    TransportSocketParams -> TransportConnectJobHelper
+        [arrowhead=diamond, color=red];
+
+    ConnectJob -> ConnectJob_Delegate
+        [dir=back, arrowhead=none, arrowtail=odiamond];
+    HigherLayeredPool -> ClientSocketPoolBaseHelper
+        [arrowhead=odiamond, taillabel="*"];
+    LowerLayeredPool -> ClientSocketPoolBaseHelper
+        [arrowhead=odiamond, taillabel="*"];
+    ClientSocketFactory -> ClientSocketPoolBaseHelper [arrowhead=odiamond];
+
+    subgraph {
+        rank=same;
+        ClientSocketPoolBaseHelper_ConnectJobFactory -> ConnectJob
+            [arrowhead=veevee];
+    }
+    ClientSocketPoolBase_ConnectJobFactory -> ConnectJob [arrowhead=veevee];
+    ClientSocketFactory -> TCPClientSocket [arrowhead=veevee]
+}
+