crypto/tls: document that ConnectionState is valid only after handshake

Conn.ConnectionState reports details that are only populated once the
TLS handshake has completed. Callers that read it immediately after
Accept (for example via tls.NewListener) instead observe an
unpopulated ConnectionState whose HandshakeComplete field is false.

Document this precondition on Conn.ConnectionState and point to
ConnectionState.HandshakeComplete and Conn.Handshake, which the first
Conn.Read or Conn.Write runs automatically.

Fixes #79828.

Change-Id: Iad8a446ae45c7eb45efba6f8c1ce50fa727db989
GitHub-Last-Rev: a9ea8721fe40ffaa44bdab16504f04212ce9980b
GitHub-Pull-Request: golang/go#80081
Reviewed-on: https://go-review.googlesource.com/c/go/+/792720
Reviewed-by: Roland Shoemaker <roland@golang.org>
LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Filippo Valsorda <filippo@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

src/crypto/tls/conn.go

diff --git a/src/crypto/tls/conn.go b/src/crypto/tls/conn.go
index fb1e9f0..e810278 100644
--- a/src/crypto/tls/conn.go
+++ b/src/crypto/tls/conn.go
@@ -1604,6 +1604,12 @@
 }
 
 // ConnectionState returns basic TLS details about the connection.
+//
+// The returned [ConnectionState] is only meaningful after the handshake has
+// completed, as reported by [ConnectionState.HandshakeComplete]; before then
+// its fields are not populated. The handshake is run automatically by the
+// first [Conn.Read] or [Conn.Write], or it can be triggered explicitly with
+// [Conn.Handshake].
 func (c *Conn) ConnectionState() ConnectionState {
 	c.handshakeMutex.Lock()
 	defer c.handshakeMutex.Unlock()