cmd/go/internal/get: improve -insecure deprecation docs

Updates #37519

Change-Id: I212607f1839b729d7da24b1258e56997b13ad830
GitHub-Last-Rev: db6d3c8
GitHub-Pull-Request: #41613
Reviewed-on: https://go-review.googlesource.com/c/go/+/257157
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Jay Conrod <jayconrod@google.com>
Trust: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
Reviewed-by: Jay Conrod <jayconrod@google.com>

doc/go1.16.html

@@ -90,12 +90,13 @@ <h4 id="go-test"><code>go</code> <code>test</code></h4>
 
 <p><!-- golang.org/issue/37519 -->
   The <code>go</code> <code>get</code> <code>-insecure</code> flag is
-  deprecated and will be removed in a future version. The <code>GOINSECURE</code>
-  environment variable should be used instead, since it provides control
-  over which modules may be retrieved using an insecure scheme. Unlike the
-  <code>-insecure</code> flag, <code>GOINSECURE</code> does not disable module
-  sum validation using the checksum database. The <code>GOPRIVATE</code> or
-  <code>GONOSUMDB</code> environment variables may be used instead.
+  deprecated and will be removed in a future version. This flag permits
+  fetching from repositories and resolving custom domains using insecure
+  schemes such as HTTP, and also bypassess module sum validation using the
+  checksum database. To permit the use of insecure schemes, use the
+  <code>GOINSECURE</code> environment variable instead. To bypass module
+  sum validation, use <code>GOPRIVATE</code> or <code>GONOSUMDB</code>.
+  See <code>go</code> <code>help</code> <code>environment</code> for details.
 </p>
 
 <h4 id="all-pattern">The <code>all</code> pattern</h4>

src/cmd/go/internal/get/get.go

@@ -46,8 +46,8 @@ before resolving dependencies or building the code.
 The -insecure flag permits fetching from repositories and resolving
 custom domains using insecure schemes such as HTTP. Use with caution.
 This flag is deprecated and will be removed in a future version of go.
-The GOINSECURE environment variable is usually a better alternative, since
-it provides control over which modules may be retrieved using an insecure
+The GOINSECURE environment variable should be used instead, since it
+provides control over which packages may be retrieved using an insecure
 scheme. See 'go help environment' for details.
 
 The -t flag instructs get to also download the packages required to build

src/cmd/go/internal/modget/get.go

@@ -115,13 +115,12 @@ require downgrading other dependencies, and 'go get' does
 this automatically as well.
 
 The -insecure flag permits fetching from repositories and resolving
-custom domains using insecure schemes such as HTTP. Use with caution.
+custom domains using insecure schemes such as HTTP, and also bypassess
+module sum validation using the checksum database. Use with caution.
 This flag is deprecated and will be removed in a future version of go.
-The GOINSECURE environment variable is usually a better alternative, since
-it provides control over which modules may be retrieved using an insecure
-scheme. It should be noted that the -insecure flag also turns the module
-checksum validation off. GOINSECURE does not do that, use GONOSUMDB.
-See 'go help environment' for details.
+To permit the use of insecure schemes, use the GOINSECURE environment
+variable instead. To bypass module sum validation, use GOPRIVATE or
+GONOSUMDB. See 'go help environment' for details.
 
 The second step is to download (if needed), build, and install
 the named packages.