Add some docs to URLRequestContextBuilder.

net/url_request/url_request_context_builder.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This class is useful for building a simple URLRequestContext. Most creators
 // of new URLRequestContexts should use this helper class to construct it. Call
 // any configuration params, and when done, invoke Build() to construct the
 // URLRequestContext. This URLRequestContext will own all its own storage.
 //
 // URLRequestContextBuilder and its associated params classes are initially
@@ skipping 38 matching lines @@
 class ChannelIDService;
 class CookieStore;
 class CTVerifier;
 class HttpAuthHandlerFactory;
 class HttpServerProperties;
 class NetworkQualityEstimator;
 class ProxyConfigService;
 class URLRequestContext;
 class URLRequestInterceptor;
 
+// A URLRequestContextBuilder creates a single URLRequestContext. It provides
+// methods to manage various URLRequestContext components which should be called
+// before creating the Context. Once configuration is complete, calling Build()
+// will create a URLRequestContext with the specified configuration. Components
+// that are not explicitly configured will use reasonable in-memory defaults.
+//
+// The returned URLRequestContext is self-contained: Deleting it will safely
+// shut down all of the URLRequests owned by its internal components, and then
+// tear down those components. The only exception to this are objects not owned
+// by URLRequestContext. This includes components passed in to the methods that
+// take raw pointers, and objects that components passed in to the Builder have
+// raw pointers to.
+//
+// A Builder should be destroyed after calling Build, and there is no need to
+// keep it around for the lifetime of the created URLRequestContext. Each
+// Builder may be used to create only a single URLRequestContext.
 class NET_EXPORT URLRequestContextBuilder {
  public:
   struct NET_EXPORT HttpCacheParams {
     enum Type {
       // In-memory cache.
       IN_MEMORY,
       // Disk cache using "default" backend.
       DISK,
       // Disk cache using "simple" backend (SimpleBackendImpl).
       DISK_SIMPLE,
@@ skipping 238 matching lines @@
   // result will be "Content-Encoding: sdch" advertisements, but no
   // dictionaries fetches and no specific dictionaries advertised.
   // SdchOwner in net/sdch/sdch_owner.h is a simple policy object.
   void set_sdch_enabled(bool enable) { sdch_enabled_ = enable; }
 
   // Sets a specific HttpServerProperties for use in the
   // URLRequestContext rather than creating a default HttpServerPropertiesImpl.
   void SetHttpServerProperties(
       std::unique_ptr<HttpServerProperties> http_server_properties);
 
+  // Creates a mostly self-contained URLRequestContext. May only be called once
+  // per URLRequestContextBuilder. After this is called, the Builder can be
+  // safely destroyed.
   std::unique_ptr<URLRequestContext> Build();
 
  protected:
   // Lets subclasses override ProxyService creation, using a ProxyService that
   // uses the URLRequestContext itself to get PAC scripts. When this method is
   // invoked, the URLRequestContext is not yet ready to service requests.
   virtual std::unique_ptr<ProxyService> CreateProxyService(
       std::unique_ptr<ProxyConfigService> proxy_config_service,
       URLRequestContext* url_request_context,
       HostResolver* host_resolver,
@@ skipping 43 matching lines @@
   std::unique_ptr<HttpServerProperties> http_server_properties_;
   std::map<std::string, std::unique_ptr<URLRequestJobFactory::ProtocolHandler>>
       protocol_handlers_;
 
   DISALLOW_COPY_AND_ASSIGN(URLRequestContextBuilder);
 };
 
 }  // namespace net
 
 #endif  // NET_URL_REQUEST_URL_REQUEST_CONTEXT_BUILDER_H_