cloud: document connection pooling mechanics and client transports
Addresses issues and
// See the License for the specific language governing permissions and
// limitations under the License.
-// Package cloud is the root of the packages used to access Google Cloud
-// Services. See https://godoc.org/cloud.google.com/go for a full list
-// of sub-packages.
-//
-// This package documents how to authorize and authenticate the sub packages.
+/*
+Package cloud is the root of the packages used to access Google Cloud
+Services. See https://godoc.org/cloud.google.com/go for a full list
+of sub-packages.
+
+Examples in this package show ways to authorize and authenticate the
+sub packages.
+
+Connection Pooling
+
+Connection pooling differs in clients based on their transport. Cloud
+clients either rely on HTTP or gRPC transports to communicate
+with Google Cloud.
+
+Cloud clients that use HTTP rely on the underlying HTTP transport to
+cache connections for later re-use. These are cached to the default
+http.MaxIdleConns and http.MaxIdleConnsPerHost settings in
+http.DefaultTransport.
+
+For gPRC clients, connection pooling is configurable to the user. Users of
+cloud client libraries may specify option.WithGRPCConnectionPool(n)
+as a client option to NewClient calls. This configures the underlying
+gRPC connections to be pooled and addressed in a round robin fashion.
+The recommended size is GOMAXPROCS.
+
+Client Transports
+
+The following clients use HTTP: bigquery, compute, storage, translate.
+
+The following clients use gRPC: bigtable, container, dataproc, datastore,
+debugger, dlp, errorreporting, firestore, iam, language, logging,
+longrunning, monitoring, oslogin, profiler, pubsub, rpcreplay, spanner,
+speech, trace, videointelligence, vision.
+
+*/
package cloud // import "cloud.google.com/go"
