Improve docs and add more examples

Author: nhooyr

README.md

@@ -31,36 +31,32 @@ go get nhooyr.io/websocket
 - [ ] WebSockets over HTTP/2 [#4](https://github.com/nhooyr/websocket/issues/4)
 - [ ] Deflate extension support [#5](https://github.com/nhooyr/websocket/issues/5)
 
-## Example
+## Examples
 
 For a production quality example that shows off the full API, see the [echo example on the godoc](https://godoc.org/nhooyr.io/websocket#example-package--Echo).
 
 ### Server
 
 ```go
-http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+http.HandlerFunc(func (w http.ResponseWriter, r *http.Request) {
 	c, err := websocket.Accept(w, r, websocket.AcceptOptions{})
 	if err != nil {
 		// ...
 	}
-	defer c.Close(websocket.StatusInternalError, "")
+	defer c.Close(websocket.StatusInternalError, "the sky is falling")
 
 	ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
 	defer cancel()
-
-	_, r, err := c.Reader(ctx)
-	if err != nil {
-		// ...
-	}
 
-	b, err := ioutil.ReadAll(r)
+	var v interface{}
+	err = wsjson.Read(ctx, c, &v)
 	if err != nil {
 		// ...
 	}
 
-	fmt.Printf("received %q\n", b)
+	log.Printf("received: %v", v)
 
-	c.Close(websocket.StatusNormalClosure, "")
+	c.Close(websocket.StatusNormalClosure, "success")
 })
 ```
 
@@ -71,27 +67,17 @@ ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
 defer cancel()
 
 c, _, err := websocket.Dial(ctx, "ws://localhost:8080", websocket.DialOptions{})
-if err != nil {
-	return err
-}
-defer c.Close(websocket.StatusInternalError, "")
-
-ww, err := c.Writer(ctx)
-if err != nil {
-	// ...
-}
-
-_, err = w.Write([]byte("hi"))
 if err != nil {
 	// ...
 }
+defer c.Close(websocket.StatusInternalError, "the sky is falling")
 
-err = w.Close()
+err = wsjson.Write(ctx, c, "hi")
 if err != nil {
 	// ...
 }
 
-c.Close(websocket.StatusNormalClosure, "")
+c.Close(websocket.StatusNormalClosure, "done")
 ```
 
 ## Design considerations

ci/bench/Dockerfile

@@ -1,9 +1,9 @@
 FROM golang:1.12
 
 LABEL "com.github.actions.name"="bench"
-LABEL "com.github.actions.description"="bench"
+LABEL "com.github.actions.description"=""
 LABEL "com.github.actions.icon"="code"
-LABEL "com.github.actions.color"="purple"
+LABEL "com.github.actions.color"="red"
 
 COPY entrypoint.sh /entrypoint.sh
 

ci/fmt/Dockerfile

@@ -1,9 +1,9 @@
 FROM golang:1.12
 
 LABEL "com.github.actions.name"="fmt"
-LABEL "com.github.actions.description"="fmt"
+LABEL "com.github.actions.description"=""
 LABEL "com.github.actions.icon"="code"
-LABEL "com.github.actions.color"="purple"
+LABEL "com.github.actions.color"="blue"
 
 COPY entrypoint.sh /entrypoint.sh
 

ci/lint/Dockerfile

@@ -1,9 +1,9 @@
 FROM codercom/playcicache
 
 LABEL "com.github.actions.name"="lint"
-LABEL "com.github.actions.description"="lint"
+LABEL "com.github.actions.description"=""
 LABEL "com.github.actions.icon"="code"
-LABEL "com.github.actions.color"="purple"
+LABEL "com.github.actions.color"="pink"
 
 COPY entrypoint.sh /entrypoint.sh
 

ci/test/Dockerfile

@@ -1,9 +1,9 @@
 FROM golang:1.12
 
 LABEL "com.github.actions.name"="test"
-LABEL "com.github.actions.description"="test"
+LABEL "com.github.actions.description"=""
 LABEL "com.github.actions.icon"="code"
-LABEL "com.github.actions.color"="purple"
+LABEL "com.github.actions.color"="green"
 
 RUN apt update && \
 	apt install -y shellcheck python-pip && \

doc.go

@@ -9,7 +9,7 @@
 // a WebSocket server, Accept to accept a WebSocket client dial and then Conn to interact
 // with the resulting WebSocket connections.
 //
-// The echo example is the best way to understand how to correctly use the library.
+// The examples are the best way to understand how to correctly use the library.
 //
-// The wsjson and wspb packages contain helpers for JSON and ProtoBuf messages.
+// The wsjson and wspb subpackages contain helpers for JSON and ProtoBuf messages.
 package websocket

example_echo_test.go

@@ -50,18 +50,18 @@ func Example_echo() {
 		}
 	}()
 
-	// Now we dial the server and send the messages.
+	// Now we dial the server, send the messages and echo the responses.
 	err = client("ws://" + l.Addr().String())
 	if err != nil {
 		log.Fatalf("client failed: %v", err)
 	}
 
 	// Output:
-	// 0
-	// 1
-	// 2
-	// 3
-	// 4
+	// received: map[i:0]
+	// received: map[i:1]
+	// received: map[i:2]
+	// received: map[i:3]
+	// received: map[i:4]
 }
 
 // echoServer is the WebSocket echo server implementation.
@@ -74,7 +74,7 @@ func echoServer(w http.ResponseWriter, r *http.Request) error {
 	if err != nil {
 		return err
 	}
-	defer c.Close(websocket.StatusInternalError, "")
+	defer c.Close(websocket.StatusInternalError, "the sky is falling")
 
 	if c.Subprotocol() == "" {
 		c.Close(websocket.StatusPolicyViolation, "cannot communicate with the default protocol")
@@ -138,7 +138,7 @@ func client(url string) error {
 	if err != nil {
 		return err
 	}
-	defer c.Close(websocket.StatusInternalError, "")
+	defer c.Close(websocket.StatusInternalError, "the sky is falling")
 
 	for i := 0; i < 5; i++ {
 		err = wsjson.Write(ctx, c, map[string]int{
@@ -154,9 +154,9 @@ func client(url string) error {
 			return err
 		}
 
-		fmt.Printf("%v\n", v["i"])
+		fmt.Printf("received: %v\n", v)
 	}
 
-	c.Close(websocket.StatusNormalClosure, "")
+	c.Close(websocket.StatusNormalClosure, "done")
 	return nil
 }

example_test.go

@@ -0,0 +1,58 @@
+package websocket_test
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"time"
+
+	"nhooyr.io/websocket"
+	"nhooyr.io/websocket/wsjson"
+)
+
+func ExampleAccept() {
+	fn := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		c, err := websocket.Accept(w, r, websocket.AcceptOptions{})
+		if err != nil {
+			log.Println(err)
+			return
+		}
+		defer c.Close(websocket.StatusInternalError, "the sky is falling")
+
+		ctx, cancel := context.WithTimeout(r.Context(), time.Second*10)
+		defer cancel()
+
+		var v interface{}
+		err = wsjson.Read(ctx, c, &v)
+		if err != nil {
+			log.Println(err)
+			return
+		}
+
+		log.Printf("received: %v", v)
+
+		c.Close(websocket.StatusNormalClosure, "success")
+	})
+
+	http.ListenAndServe("localhost:8080", fn)
+}
+
+func ExampleDial() {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	c, _, err := websocket.Dial(ctx, "ws://localhost:8080", websocket.DialOptions{})
+	if err != nil {
+		log.Println(err)
+		return
+	}
+	defer c.Close(websocket.StatusInternalError, "the sky is falling")
+
+	err = wsjson.Write(ctx, c, "hi")
+	if err != nil {
+		log.Println(err)
+		return
+	}
+
+	c.Close(websocket.StatusNormalClosure, "done")
+}

statuscode.go

@@ -42,7 +42,7 @@ const (
 	statusTLSHandshake
 )
 
-// CloseError represents an error from a WebSocket close frame.
+// CloseError represents a WebSocket close frame.
 // It is returned by Conn's methods when the Connection is closed with a WebSocket close frame.
 type CloseError struct {
 	Code   StatusCode