diff --git a/doc.go b/doc.go
index 57fb06da81..853036c026 100755
--- a/doc.go
+++ b/doc.go
@@ -42,6 +42,8 @@ Call the Elasticsearch APIs by invoking the corresponding methods on the client:
 
 		log.Println(res)
 
-See the github.com/elastic/go-elasticsearch/esapi package for more information and examples.
+See the github.com/elastic/go-elasticsearch/esapi package for more information about using the API.
+
+See the github.com/elastic/go-elasticsearch/estransport package for more information about configuring the transport.
 */
 package elasticsearch
diff --git a/esapi/doc.go b/esapi/doc.go
index 6a8aedf8fd..9ec8084777 100755
--- a/esapi/doc.go
+++ b/esapi/doc.go
@@ -85,10 +85,11 @@ about the API endpoints and parameters.
 The Go API is generated from the Elasticsearch JSON specification at
 https://github.com/elastic/elasticsearch/tree/master/rest-api-spec/src/main/resources/rest-api-spec/api
 by the internal package available at
-https://github.com/elastic/go-elasticsearch/tree/master/internal/cmd/generate/commands.
+https://github.com/elastic/go-elasticsearch/tree/master/internal/cmd/generate/commands/gensource.
 
 The API is tested by integration tests common to all Elasticsearch official clients, generated from the
-source at https://github.com/elastic/elasticsearch/tree/master/rest-api-spec/src/main/resources/rest-api-spec/test. The generator is provided by the internal package internal/cmd/generate.
+source at https://github.com/elastic/elasticsearch/tree/master/rest-api-spec/src/main/resources/rest-api-spec/test.
+The generator is provided by the internal package available at internal/cmd/generate/commands/gentests.
 
 */
 package esapi
diff --git a/estransport/doc.go b/estransport/doc.go
index aa3eba3f95..630ffbaf60 100755
--- a/estransport/doc.go
+++ b/estransport/doc.go
@@ -4,12 +4,24 @@ Package estransport provides the transport layer for the Elasticsearch client.
 It is automatically included in the client provided by the github.com/elastic/go-elasticsearch package
 and is not intended for direct use: to configure the client, use the elasticsearch.Config struct.
 
-The default HTTP transport of the client is http.Transport.
+The default HTTP transport of the client is http.Transport; use the Transport option to customize it;
+see the _examples/customization.go file in this repository for information.
 
 The package defines the "Selector" interface for getting a URL from the list. At the moment,
 the implementation is rather minimal: the client takes a slice of url.URL pointers,
 and round-robins across them when performing the request.
 
+The package will automatically retry requests on network-related errors, and on specific
+response status codes (by default 502, 503, 504). Use the RetryOnStatus option to customize the list.
+The transport will not retry a timeout network error, unless enabled by setting
+EnableRetryOnTimeout to true.
+
+Use the MaxRetries option to configure the number of retries, and set DisableRetry to true
+to disable the retry behaviour altogether.
+
+By default, the retry will be performed without any delay; to configure a backoff interval,
+implement the RetryBackoff option function; see an example in the package unit tests for information.
+
 The package defines the "Logger" interface for logging information about request and response.
 It comes with several bundled loggers for logging in text and JSON.