quic: expand package docs, and document Stream

For golang/go#58547

Change-Id: Ie5dd0ed383ea7a5b3a45103cb730ff62792f62e1
Reviewed-on: https://go-review.googlesource.com/c/net/+/565797
Reviewed-by: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

2 files changed, 54 insertions, 3 deletions

diff --git a/internal/quic/doc.go b/internal/quic/doc.go
index 2fe17fe..2fd10f0 100644
--- a/internal/quic/doc.go
+++ b/internal/quic/doc.go
@@ -2,8 +2,44 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package quic is an experimental, incomplete implementation of the QUIC protocol.
-// This package is a work in progress, and is not ready for use at this time.
+// Package quic implements the QUIC protocol.
 //
-// This package implements (or will implement) RFC 9000, RFC 9001, and RFC 9002.
+// This package is a work in progress.
+// It is not ready for production usage.
+// Its API is subject to change without notice.
+//
+// This package is low-level.
+// Most users will use it indirectly through an HTTP/3 implementation.
+//
+// # Usage
+//
+// An [Endpoint] sends and receives traffic on a network address.
+// Create an Endpoint to either accept inbound QUIC connections
+// or create outbound ones.
+//
+// A [Conn] is a QUIC connection.
+//
+// A [Stream] is a QUIC stream, an ordered, reliable byte stream.
+//
+// # Cancelation
+//
+// All blocking operations may be canceled using a context.Context.
+// When performing an operation with a canceled context, the operation
+// will succeed if doing so does not require blocking. For example,
+// reading from a stream will return data when buffered data is available,
+// even if the stream context is canceled.
+//
+// # Limitations
+//
+// This package is a work in progress.
+// Known limitations include:
+//
+//   - Performance is untuned.
+//   - 0-RTT is not supported.
+//   - Address migration is not supported.
+//   - Server preferred addresses are not supported.
+//   - The latency spin bit is not supported.
+//   - Stream send/receive windows are configurable,
+//     but are fixed and do not adapt to available throughput.
+//   - Path MTU discovery is not implemented.
 package quic
diff --git a/internal/quic/stream.go b/internal/quic/stream.go
index c5fafdf..cb45534 100644
--- a/internal/quic/stream.go
+++ b/internal/quic/stream.go
@@ -14,6 +14,21 @@ import (
 	"math"
 )
 
+// A Stream is an ordered byte stream.
+//
+// Streams may be bidirectional, read-only, or write-only.
+// Methods inappropriate for a stream's direction
+// (for example, [Write] to a read-only stream)
+// return errors.
+//
+// It is not safe to perform concurrent reads from or writes to a stream.
+// It is safe, however, to read and write at the same time.
+//
+// Reads and writes are buffered.
+// It is generally not necessary to wrap a stream in a [bufio.ReadWriter]
+// or otherwise apply additional buffering.
+//
+// To cancel reads or writes, use the [SetReadContext] and [SetWriteContext] methods.
 type Stream struct {
 	id   streamID
 	conn *Conn