Improve docs and fix examples

Closes #207

Author: nhooyr

README.md

@@ -15,9 +15,9 @@ go get nhooyr.io/websocket
 - Minimal and idiomatic API
 - First class [context.Context](https://blog.golang.org/context) support
 - Fully passes the WebSocket [autobahn-testsuite](https://github.com/crossbario/autobahn-testsuite)
-- Thorough unit tests with [90% coverage](https://coveralls.io/github/nhooyr/websocket)
-- [Minimal dependencies](https://pkg.go.dev/nhooyr.io/websocket?tab=imports)
-- JSON and protobuf helpers in the [wsjson](https://pkg.go.dev/nhooyr.io/websocket/wsjson?tab=doc) and [wspb](https://pkg.go.dev/nhooyr.io/websocket/wspb?tab=doc) subpackages
+- Thorough tests with [90% coverage](https://coveralls.io/github/nhooyr/websocket)
+- [Zero dependencies](https://pkg.go.dev/nhooyr.io/websocket?tab=imports)
+- JSON and protobuf helpers in the [wsjson](https://pkg.go.dev/nhooyr.io/websocket/wsjson) and [wspb](https://pkg.go.dev/nhooyr.io/websocket/wspb) subpackages
 - Zero alloc reads and writes
 - Concurrent writes
 - [Close handshake](https://godoc.org/nhooyr.io/websocket#Conn.Close)
@@ -32,9 +32,10 @@ go get nhooyr.io/websocket
 
 ## Examples
 
-For a production quality example that demonstrates the complete API, see the [echo example](https://godoc.org/nhooyr.io/websocket#example-package--Echo).
+For a production quality example that demonstrates the complete API, see the
+[echo example](./examples/echo).
 
-For a full stack example, see [./chat-example](./chat-example).
+For a full stack example, see the [chat example](./examples/chat).
 
 ### Server
 
@@ -98,7 +99,7 @@ Advantages of nhooyr.io/websocket:
 - [net.Conn](https://godoc.org/nhooyr.io/websocket#NetConn) wrapper
 - Zero alloc reads and writes ([gorilla/websocket#535](https://github.com/gorilla/websocket/issues/535))
 - Full [context.Context](https://blog.golang.org/context) support
-- Dials use [net/http.Client](https://golang.org/pkg/net/http/#Client)
+- Dial uses [net/http.Client](https://golang.org/pkg/net/http/#Client)
   - Will enable easy HTTP/2 support in the future
   - Gorilla writes directly to a net.Conn and so duplicates features of net/http.Client.
 - Concurrent writes
@@ -111,7 +112,7 @@ Advantages of nhooyr.io/websocket:
   - Gorilla's implementation is slower and uses [unsafe](https://golang.org/pkg/unsafe/).
 - Full [permessage-deflate](https://tools.ietf.org/html/rfc7692) compression extension support
   - Gorilla only supports no context takeover mode
-  - We use [klauspost/compress](https://github.com/klauspost/compress) for much lower memory usage ([gorilla/websocket#203](https://github.com/gorilla/websocket/issues/203))
+  - We use a vendored [klauspost/compress](https://github.com/klauspost/compress) for much lower memory usage ([gorilla/websocket#203](https://github.com/gorilla/websocket/issues/203))
 - [CloseRead](https://godoc.org/nhooyr.io/websocket#Conn.CloseRead) helper ([gorilla/websocket#492](https://github.com/gorilla/websocket/issues/492))
 - Actively maintained ([gorilla/websocket#370](https://github.com/gorilla/websocket/issues/370))
 
@@ -120,7 +121,7 @@ Advantages of nhooyr.io/websocket:
 [golang.org/x/net/websocket](https://godoc.org/golang.org/x/net/websocket) is deprecated.
 See [golang/go/issues/18152](https://github.com/golang/go/issues/18152).
 
-The [net.Conn](https://godoc.org/nhooyr.io/websocket#NetConn) wrapper will ease in transitioning
+The [net.Conn](https://godoc.org/nhooyr.io/websocket#NetConn) can help in transitioning
 to nhooyr.io/websocket.
 
 #### gobwas/ws

ci/test.mk

@@ -14,4 +14,4 @@ gotest:
 	go test -timeout=30m -covermode=atomic -coverprofile=ci/out/coverage.prof -coverpkg=./... $${GOTESTFLAGS-} ./...
 	sed -i '/stringer\.go/d' ci/out/coverage.prof
 	sed -i '/nhooyr.io\/websocket\/internal\/test/d' ci/out/coverage.prof
-	sed -i '/chat-example/d' ci/out/coverage.prof
+	sed -i '/example/d' ci/out/coverage.prof

example_test.go

@@ -4,17 +4,16 @@ import (
 	"context"
 	"log"
 	"net/http"
-	"os"
-	"os/signal"
 	"time"
 
 	"nhooyr.io/websocket"
 	"nhooyr.io/websocket/wsjson"
 )
 
-// This example accepts a WebSocket connection, reads a single JSON
-// message from the client and then closes the connection.
 func ExampleAccept() {
+	// This handler accepts a WebSocket connection, reads a single JSON
+	// message from the client and then closes the connection.
+
 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		c, err := websocket.Accept(w, r, nil)
 		if err != nil {
@@ -40,9 +39,10 @@ func ExampleAccept() {
 	log.Fatal(err)
 }
 
-// This example dials a server, writes a single JSON message and then
-// closes the connection.
 func ExampleDial() {
+	// Dials a server, writes a single JSON message and then
+	// closes the connection.
+
 	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
 	defer cancel()
 
@@ -60,9 +60,10 @@ func ExampleDial() {
 	c.Close(websocket.StatusNormalClosure, "")
 }
 
-// This example dials a server and then expects to be disconnected with status code
-// websocket.StatusNormalClosure.
 func ExampleCloseStatus() {
+	// Dials a server and then expects to be disconnected with status code
+	// websocket.StatusNormalClosure.
+
 	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
 	defer cancel()
 
@@ -78,9 +79,9 @@ func ExampleCloseStatus() {
 	}
 }
 
-// This example shows how to correctly handle a WebSocket connection
-// on which you will only write and do not expect to read data messages.
 func Example_writeOnly() {
+	// This handler demonstrates how to correctly handle a write only WebSocket connection.
+	// i.e you only expect to write messages and do not expect to read any messages.
 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		c, err := websocket.Accept(w, r, nil)
 		if err != nil {
@@ -116,9 +117,9 @@ func Example_writeOnly() {
 	log.Fatal(err)
 }
 
-// This example demonstrates how to safely accept cross origin WebSockets
-// from the origin example.com.
 func Example_crossOrigin() {
+	// This handler demonstrates how to safely accept cross origin WebSockets
+	// from the origin example.com.
 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		c, err := websocket.Accept(w, r, &websocket.AcceptOptions{
 			OriginPatterns: []string{"example.com"},
@@ -141,52 +142,57 @@ func Example_crossOrigin() {
 // for 10 seconds.
 // If you CTRL+C while a connection is open, it will wait at most 30s
 // for all connections to terminate before shutting down.
-func ExampleGrace() {
-	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		c, err := websocket.Accept(w, r, nil)
-		if err != nil {
-			log.Println(err)
-			return
-		}
-		defer c.Close(websocket.StatusInternalError, "the sky is falling")
-
-		ctx := c.CloseRead(r.Context())
-		select {
-		case <-ctx.Done():
-		case <-time.After(time.Second * 10):
-		}
-
-		c.Close(websocket.StatusNormalClosure, "")
-	})
-
-	var g websocket.Grace
-	s := &http.Server{
-		Handler:      g.Handler(fn),
-		ReadTimeout:  time.Second * 15,
-		WriteTimeout: time.Second * 15,
-	}
-
-	errc := make(chan error, 1)
-	go func() {
-		errc <- s.ListenAndServe()
-	}()
-
-	sigs := make(chan os.Signal, 1)
-	signal.Notify(sigs, os.Interrupt)
-	select {
-	case err := <-errc:
-		log.Printf("failed to listen and serve: %v", err)
-	case sig := <-sigs:
-		log.Printf("terminating: %v", sig)
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
-	defer cancel()
-	s.Shutdown(ctx)
-	g.Shutdown(ctx)
-}
+// func ExampleGrace() {
+// 	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+// 		c, err := websocket.Accept(w, r, nil)
+// 		if err != nil {
+// 			log.Println(err)
+// 			return
+// 		}
+// 		defer c.Close(websocket.StatusInternalError, "the sky is falling")
+//
+// 		ctx := c.CloseRead(r.Context())
+// 		select {
+// 		case <-ctx.Done():
+// 		case <-time.After(time.Second * 10):
+// 		}
+//
+// 		c.Close(websocket.StatusNormalClosure, "")
+// 	})
+//
+// 	var g websocket.Grace
+// 	s := &http.Server{
+// 		Handler:      g.Handler(fn),
+// 		ReadTimeout:  time.Second * 15,
+// 		WriteTimeout: time.Second * 15,
+// 	}
+//
+// 	errc := make(chan error, 1)
+// 	go func() {
+// 		errc <- s.ListenAndServe()
+// 	}()
+//
+// 	sigs := make(chan os.Signal, 1)
+// 	signal.Notify(sigs, os.Interrupt)
+// 	select {
+// 	case err := <-errc:
+// 		log.Printf("failed to listen and serve: %v", err)
+// 	case sig := <-sigs:
+// 		log.Printf("terminating: %v", sig)
+// 	}
+//
+// 	ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
+// 	defer cancel()
+// 	s.Shutdown(ctx)
+// 	g.Shutdown(ctx)
+// }
 
 // This example demonstrates full stack chat with an automated test.
 func Example_fullStackChat() {
-	// https://github.com/nhooyr/websocket/tree/master/chat-example
+	// https://github.com/nhooyr/websocket/tree/master/examples/chat
+}
+
+// This example demonstrates a echo server.
+func Example_echo() {
+	// https://github.com/nhooyr/websocket/tree/master/examples/echo
 }

examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+This directory contains more involved examples unsuitable
+for display with godoc.