Merge pull request #15 from multiformats/docs-improvements

README/docs: Fix and improve example. Add Gx instructions. Golint.

Author: Kubuxu

README.md

@@ -4,6 +4,7 @@
 [![](https://img.shields.io/badge/project-multiformats-blue.svg?style=flat-square)](https://github.com/multiformats/multiformats)
 [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](https://webchat.freenode.net/?channels=%23ipfs)
 [![](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
+[![GoDoc](https://godoc.org/github.com/multiformats/go-multistream?status.svg)](https://godoc.org/github.com/multiformats/go-multistream)
 [![Travis CI](https://img.shields.io/travis/multiformats/go-multistream.svg?style=flat-square&branch=master)](https://travis-ci.org/multiformats/go-multistream)
 [![codecov.io](https://img.shields.io/codecov/c/github/multiformats/go-multistream.svg?style=flat-square&branch=master)](https://codecov.io/github/multiformats/go-multistream?branch=master)
 
@@ -23,30 +24,62 @@ The protocol is defined [here](https://github.com/multiformats/multistream-selec
 
 ## Install
 
+`go-multistream` is a standard Go module which can be installed with:
+
 ```sh
 go get github.com/multiformats/go-multistream
 ```
 
+Note that `go-multistream` is packaged with Gx, so it is recommended to use Gx to install and use it (see Usage section).
+
+
 ## Usage
 
+### Using Gx and Gx-go
+
+This module is packaged with [Gx](https://github.com/whyrusleeping/gx). In order to use it in your own project do:
+
+```sh
+go get -u github.com/whyrusleeping/gx
+go get -u github.com/whyrusleeping/gx-go
+cd <your-project-repository>
+gx init
+gx import github.com/multiformats/go-multistream
+gx install --global
+gx-go --rewrite
+```
+
+Please check [Gx](https://github.com/whyrusleeping/gx) and [Gx-go](https://github.com/whyrusleeping/gx-go) documentation for more information.
+
+### Example
+
+
+This example shows how to use a multistream muxer. A muxer uses user-added handlers to handle different "protocols". The first step when interacting with a connection handler by the muxer is to select the protocol (the example uses `SelectProtoOrFail`). This will then let the muxer use the right handler.
+
+
 ```go
 package main
 
 import (
 	"fmt"
-	ms "github.com/multiformats/go-multistream"
 	"io"
+	"io/ioutil"
 	"net"
+
+	ms "github.com/multiformats/go-multistream"
 )
 
+// This example creates a multistream muxer, adds handlers for the protocols
+// "/cats" and "/docs" and exposes it on a localhost:8765. It then opens connections
+// to that port, selects the protocols and tests that the handlers are working.
 func main() {
 	mux := ms.NewMultistreamMuxer()
-	mux.AddHandler("/cats", func(rwc io.ReadWriteCloser) error {
-		fmt.Fprintln(rwc, "HELLO I LIKE CATS")
+	mux.AddHandler("/cats", func(proto string, rwc io.ReadWriteCloser) error {
+		fmt.Fprintln(rwc, proto, ": HELLO I LIKE CATS")
 		return rwc.Close()
 	})
-	mux.AddHandler("/dogs", func(rwc io.ReadWriteCloser) error {
-		fmt.Fprintln(rwc, "HELLO I LIKE DOGS")
+	mux.AddHandler("/dogs", func(proto string, rwc io.ReadWriteCloser) error {
+		fmt.Fprintln(rwc, proto, ": HELLO I LIKE DOGS")
 		return rwc.Close()
 	})
 
@@ -55,17 +88,54 @@ func main() {
 		panic(err)
 	}
 
-	for {
-		con, err := list.Accept()
-		if err != nil {
-			panic(err)
+	go func() {
+		for {
+			con, err := list.Accept()
+			if err != nil {
+				panic(err)
+			}
+
+			go mux.Handle(con)
 		}
+	}()
 
-		go mux.Handle(con)
+	// The Muxer is ready, let's test it
+	conn, err := net.Dial("tcp", ":8765")
+	if err != nil {
+		panic(err)
 	}
+
+	// Create a new multistream to talk to the muxer
+	// which will negotiate that we want to talk with /cats
+	mstream := ms.NewMSSelect(conn, "/cats")
+	cats, err := ioutil.ReadAll(mstream)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("%s", cats)
+	mstream.Close()
+
+	// A different way of talking to the muxer
+	// is to manually selecting the protocol ourselves
+	conn, err = net.Dial("tcp", ":8765")
+	if err != nil {
+		panic(err)
+	}
+	defer conn.Close()
+	err = ms.SelectProtoOrFail("/dogs", conn)
+	if err != nil {
+		panic(err)
+	}
+	dogs, err := ioutil.ReadAll(conn)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("%s", dogs)
+	conn.Close()
 }
 ```
 
+
 ## Maintainers
 
 Captain: [@whyrusleeping](https://github.com/whyrusleeping).

client.go

@@ -5,8 +5,14 @@ import (
 	"io"
 )
 
+// ErrNotSupported is the error returned when the muxer does not support
+// the protocol specified for the handshake.
 var ErrNotSupported = errors.New("protocol not supported")
 
+// SelectProtoOrFail performs the initial multistream handshake
+// to inform the muxer of the protocol that will be used to communicate
+// on this ReadWriteCloser. It returns an error if, for example,
+// the muxer does not know how to handle this protocol.
 func SelectProtoOrFail(proto string, rwc io.ReadWriteCloser) error {
 	err := handshake(rwc)
 	if err != nil {
@@ -16,6 +22,8 @@ func SelectProtoOrFail(proto string, rwc io.ReadWriteCloser) error {
 	return trySelect(proto, rwc)
 }
 
+// SelectOneOf will perform handshakes with the protocols on the given slice
+// until it finds one which is supported by the muxer.
 func SelectOneOf(protos []string, rwc io.ReadWriteCloser) (string, error) {
 	err := handshake(rwc)
 	if err != nil {

lazy.go

@@ -7,17 +7,25 @@ import (
 	"sync"
 )
 
+// Multistream represents in essense a ReadWriteCloser, or a single
+// communication wire which supports multiple streams on it. Each
+// stream is identified by a protocol tag.
 type Multistream interface {
 	io.ReadWriteCloser
 }
 
+// NewMSSelect returns a new Multistream which is able to perform
+// protocol selection with a MultistreamMuxer.
 func NewMSSelect(c io.ReadWriteCloser, proto string) Multistream {
 	return &lazyConn{
 		protos: []string{ProtocolID, proto},
 		con:    c,
 	}
 }
 
+// NewMultistream returns a multistream for the given protocol. This will not
+// perform any protocol selection. If you are using a MultistreamMuxer, use
+// NewMSSelect.
 func NewMultistream(c io.ReadWriteCloser, proto string) Multistream {
 	return &lazyConn{
 		protos: []string{proto},

multistream.go

@@ -1,3 +1,6 @@
+// Package multistream implements a simple stream router for the
+// multistream-select protocoli. The protocol is defined at
+// https://github.com/multiformats/multistream-select
 package multistream
 
 import (
@@ -9,23 +12,34 @@ import (
 	"sync"
 )
 
+// ErrTooLarge is an error to signal that an incoming message was too large
 var ErrTooLarge = errors.New("incoming message was too large")
 
+// ProtocolID identifies the multistream protocol itself and makes sure
+// the multistream muxers on both sides of a channel can work with each other.
 const ProtocolID = "/multistream/1.0.0"
 
-type HandlerFunc func(string, io.ReadWriteCloser) error
+// HandlerFunc is a user-provided function used by the MultistreamMuxer to
+// handle a protocol/stream.
+type HandlerFunc func(protocol string, rwc io.ReadWriteCloser) error
 
+// Handler is a wrapper to HandlerFunc which attaches a name (protocol) and a
+// match function which can optionally be used to select a handler by other
+// means than the name.
 type Handler struct {
 	MatchFunc func(string) bool
 	Handle    HandlerFunc
 	AddName   string
 }
 
+// MultistreamMuxer is a muxer for multistream. Depending on the stream
+// protocol tag it will select the right handler and hand the stream off to it.
 type MultistreamMuxer struct {
 	handlerlock sync.Mutex
 	handlers    []Handler
 }
 
+// NewMultistreamMuxer creates a muxer.
 func NewMultistreamMuxer() *MultistreamMuxer {
 	return new(MultistreamMuxer)
 }
@@ -68,6 +82,8 @@ func delimWrite(w io.Writer, mes []byte) error {
 	return nil
 }
 
+// Ls is a Multistream muxer command which returns the list of handler names
+// available on a muxer.
 func Ls(rw io.ReadWriter) ([]string, error) {
 	err := delimWriteBuffered(rw, []byte("ls"))
 	if err != nil {
@@ -97,10 +113,14 @@ func fulltextMatch(s string) func(string) bool {
 	}
 }
 
+// AddHandler attaches a new protocol handler to the muxer.
 func (msm *MultistreamMuxer) AddHandler(protocol string, handler HandlerFunc) {
 	msm.AddHandlerWithFunc(protocol, fulltextMatch(protocol), handler)
 }
 
+// AddHandlerWithFunc attaches a new protocol handler to the muxer with a match.
+// If the match function returns true for a given protocol tag, the protocol
+// will be selected even if the handler name and protocol tags are different.
 func (msm *MultistreamMuxer) AddHandlerWithFunc(protocol string, match func(string) bool, handler HandlerFunc) {
 	msm.handlerlock.Lock()
 	msm.removeHandler(protocol)
@@ -112,6 +132,7 @@ func (msm *MultistreamMuxer) AddHandlerWithFunc(protocol string, match func(stri
 	msm.handlerlock.Unlock()
 }
 
+// RemoveHandler removes the handler with the given name from the muxer.
 func (msm *MultistreamMuxer) RemoveHandler(protocol string) {
 	msm.handlerlock.Lock()
 	defer msm.handlerlock.Unlock()
@@ -128,6 +149,7 @@ func (msm *MultistreamMuxer) removeHandler(protocol string) {
 	}
 }
 
+// Protocols returns the list of handler-names added to this this muxer.
 func (msm *MultistreamMuxer) Protocols() []string {
 	var out []string
 	msm.handlerlock.Lock()
@@ -138,6 +160,8 @@ func (msm *MultistreamMuxer) Protocols() []string {
 	return out
 }
 
+// ErrIncorrectVersion is an error reported when the muxer protocol negotiation
+// fails because of a ProtocolID mismatch.
 var ErrIncorrectVersion = errors.New("client connected with incorrect version")
 
 func (msm *MultistreamMuxer) findHandler(proto string) *Handler {
@@ -153,6 +177,10 @@ func (msm *MultistreamMuxer) findHandler(proto string) *Handler {
 	return nil
 }
 
+// NegotiateLazy performs protocol selection and returns
+// a multistream, the protocol used, the handler and an error. It is lazy
+// because the write-handshake is performed on a subroutine, allowing this
+// to return before that handshake is completed.
 func (msm *MultistreamMuxer) NegotiateLazy(rwc io.ReadWriteCloser) (Multistream, string, HandlerFunc, error) {
 	pval := make(chan string, 1)
 	writeErr := make(chan error, 1)
@@ -239,6 +267,8 @@ loop:
 	}
 }
 
+// Negotiate performs protocol selection and returns the protocol name and
+// the matching handler function for it (or an error).
 func (msm *MultistreamMuxer) Negotiate(rwc io.ReadWriteCloser) (string, HandlerFunc, error) {
 	// Send our protocol ID
 	err := delimWriteBuffered(rwc, []byte(ProtocolID))
@@ -292,6 +322,8 @@ loop:
 
 }
 
+// Ls implements the "ls" command which writes the list of
+// supported protocols to the given Writer.
 func (msm *MultistreamMuxer) Ls(w io.Writer) error {
 	buf := new(bytes.Buffer)
 	msm.handlerlock.Lock()
@@ -317,6 +349,9 @@ func (msm *MultistreamMuxer) Ls(w io.Writer) error {
 	return err
 }
 
+// Handle performs protocol negotiation on a ReadWriteCloser
+// (i.e. a connection). It will find a matching handler for the
+// incoming protocol and pass the ReadWriteCloser to it.
 func (msm *MultistreamMuxer) Handle(rwc io.ReadWriteCloser) error {
 	p, h, err := msm.Negotiate(rwc)
 	if err != nil {
@@ -325,6 +360,8 @@ func (msm *MultistreamMuxer) Handle(rwc io.ReadWriteCloser) error {
 	return h(p, rwc)
 }
 
+// ReadNextToken extracts a token from a ReadWriter. It is used during
+// protocol negotiation and returns a string.
 func ReadNextToken(rw io.ReadWriter) (string, error) {
 	tok, err := ReadNextTokenBytes(rw)
 	if err != nil {
@@ -334,6 +371,8 @@ func ReadNextToken(rw io.ReadWriter) (string, error) {
 	return string(tok), nil
 }
 
+// ReadNextTokenBytes extracts a token from a ReadWriter. It is used
+// during protocol negotiation and returns a byte slice.
 func ReadNextTokenBytes(rw io.ReadWriter) ([]byte, error) {
 	data, err := lpReadBuf(rw)
 	switch err {