Merge pull request #26 from multiformats/docs-improvements

README/docs: Improved README, make golint happy

README.md

@@ -4,10 +4,12 @@
 [![](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-multiaddr-net?status.svg)](https://godoc.org/github.com/multiformats/go-multiaddr-net)
 [![Travis CI](https://img.shields.io/travis/multiformats/go-multiaddr-net.svg?style=flat-square&branch=master)](https://travis-ci.org/multiformats/go-multiaddr-net)
-[![codecov.io](https://img.shields.io/codecov/c/github/multiformats/go-multiaddr-net.svg?style=flat-square&branch=master)](https://codecov.io/github/multiformats/go-multiaddr-net?branch=master)
 
-> multiaddr net tools
+<!---[![codecov.io](https://img.shields.io/codecov/c/github/multiformats/go-multiaddr-net.svg?style=flat-square&branch=master)](https://codecov.io/github/multiformats/go-multiaddr-net?branch=master)--->
+
+> Multiaddress net tools
 
 This package provides [Multiaddr](https://github.com/multiformats/go-multiaddr) specific versions of common functions in [stdlib](https://github.com/golang/go/tree/master/src)'s `net` package. This means wrappers of standard net symbols like `net.Dial` and `net.Listen`, as well
 as conversion to and from `net.Addr`.
@@ -22,13 +24,32 @@ as conversion to and from `net.Addr`.
 
 ## Install
 
+`go-multiaddr-net` is a standard Go module which can be installed with:
+
 ```sh
 go get github.com/multiformats/go-multiaddr-net
 ```
 
+Note that `go-multiaddr-net` is packaged with Gx, so it is recommended to use Gx to install and use it (see Usage section).
+
+
 ## Usage
 
-See the docs:
+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-multiaddr-net
+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.
+
+For further usage, see the docs:
 
 - `multiaddr/net`: https://godoc.org/github.com/multiformats/go-multiaddr-net
 - `multiaddr`: https://godoc.org/github.com/multiformats/go-multiaddr

convert.go

@@ -15,6 +15,7 @@ func FromNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	return defaultCodecs.FromNetAddr(a)
 }
 
+// FromNetAddr converts a net.Addr to Multiaddress.
 func (cm *CodecMap) FromNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	if a == nil {
 		return nil, fmt.Errorf("nil multiaddr")
@@ -34,6 +35,7 @@ func ToNetAddr(maddr ma.Multiaddr) (net.Addr, error) {
 	return defaultCodecs.ToNetAddr(maddr)
 }
 
+// ToNetAddr converts a Multiaddress to a standard net.Addr.
 func (cm *CodecMap) ToNetAddr(maddr ma.Multiaddr) (net.Addr, error) {
 	protos := maddr.Protocols()
 	final := protos[len(protos)-1]
@@ -105,7 +107,7 @@ func DialArgs(m ma.Multiaddr) (string, string, error) {
 	return network, host, nil
 }
 
-func parseTcpNetAddr(a net.Addr) (ma.Multiaddr, error) {
+func parseTCPNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	ac, ok := a.(*net.TCPAddr)
 	if !ok {
 		return nil, errIncorrectNetAddr
@@ -127,7 +129,7 @@ func parseTcpNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	return ipm.Encapsulate(tcpm), nil
 }
 
-func parseUdpNetAddr(a net.Addr) (ma.Multiaddr, error) {
+func parseUDPNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	ac, ok := a.(*net.UDPAddr)
 	if !ok {
 		return nil, errIncorrectNetAddr
@@ -149,15 +151,15 @@ func parseUdpNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	return ipm.Encapsulate(udpm), nil
 }
 
-func parseIpNetAddr(a net.Addr) (ma.Multiaddr, error) {
+func parseIPNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	ac, ok := a.(*net.IPAddr)
 	if !ok {
 		return nil, errIncorrectNetAddr
 	}
 	return FromIP(ac.IP)
 }
 
-func parseIpPlusNetAddr(a net.Addr) (ma.Multiaddr, error) {
+func parseIPPlusNetAddr(a net.Addr) (ma.Multiaddr, error) {
 	ac, ok := a.(*net.IPNet)
 	if !ok {
 		return nil, errIncorrectNetAddr

ip.go

@@ -70,7 +70,8 @@ func IsIPLoopback(m ma.Multiaddr) bool {
 	return false
 }
 
-// IP6 Link Local addresses are non routable. The prefix is technically
+// IsIP6LinkLocal returns if a multiaddress is an IPv6 local link. These
+// addresses are non routable. The prefix is technically
 // fe80::/10, but we test fe80::/16 for simplicity (no need to mask).
 // So far, no hardware interfaces exist long enough to use those 2 bits.
 // Send a PR if there is.

net.go

@@ -1,3 +1,8 @@
+// Package manet provides Multiaddr
+// (https://github.com/multiformats/go-multiaddr) specific versions of common
+// functions in Go's standard `net` package. This means wrappers of standard
+// net symbols like `net.Dial` and `net.Listen`, as well as conversion to
+// and from `net.Addr`.
 package manet
 
 import (
@@ -90,6 +95,7 @@ func (d *Dialer) Dial(remote ma.Multiaddr) (Conn, error) {
 	return d.DialContext(context.Background(), remote)
 }
 
+// DialContext allows to provide a custom context to Dial().
 func (d *Dialer) DialContext(ctx context.Context, remote ma.Multiaddr) (Conn, error) {
 	// if a LocalAddr is specified, use it on the embedded dialer.
 	if d.LocalAddr != nil {

registry.go

@@ -8,7 +8,10 @@ import (
 	ma "github.com/multiformats/go-multiaddr"
 )
 
+// FromNetAddrFunc is a generic function which converts a net.Addr to Multiaddress
 type FromNetAddrFunc func(a net.Addr) (ma.Multiaddr, error)
+
+// ToNetAddrFunc is a generic function which converts a Multiaddress to net.Addr
 type ToNetAddrFunc func(ma ma.Multiaddr) (net.Addr, error)
 
 var defaultCodecs *CodecMap
@@ -22,13 +25,18 @@ func init() {
 	defaultCodecs.RegisterNetCodec(ipnetAddrSpec)
 }
 
+// CodecMap holds a map of NetCodecs indexed by their Protocol ID
+// along with parsers for the addresses they use.
+// It is used to keep a list of supported network address codecs (protocols
+// which addresses can be converted to and from multiaddresses).
 type CodecMap struct {
 	codecs       map[string]*NetCodec
 	addrParsers  map[string]FromNetAddrFunc
 	maddrParsers map[string]ToNetAddrFunc
 	lk           sync.Mutex
 }
 
+// NewCodecMap initializes and returns a CodecMap object.
 func NewCodecMap() *CodecMap {
 	return &CodecMap{
 		codecs:       make(map[string]*NetCodec),
@@ -37,6 +45,9 @@ func NewCodecMap() *CodecMap {
 	}
 }
 
+// NetCodec is used to identify a network codec, that is, a network type for
+// which we are able to translate multiaddresses into standard Go net.Addr
+// and back.
 type NetCodec struct {
 	// NetAddrNetworks is an array of strings that may be returned
 	// by net.Addr.Network() calls on addresses belonging to this type
@@ -55,10 +66,13 @@ type NetCodec struct {
 	Protocol ma.Protocol
 }
 
+// RegisterNetCodec adds a new NetCodec to the default codecs.
 func RegisterNetCodec(a *NetCodec) {
 	defaultCodecs.RegisterNetCodec(a)
 }
 
+// RegisterNetCodec adds a new NetCodec to the CodecMap. This function is
+// thread safe.
 func (cm *CodecMap) RegisterNetCodec(a *NetCodec) {
 	cm.lk.Lock()
 	defer cm.lk.Unlock()
@@ -73,35 +87,35 @@ func (cm *CodecMap) RegisterNetCodec(a *NetCodec) {
 var tcpAddrSpec = &NetCodec{
 	ProtocolName:     "tcp",
 	NetAddrNetworks:  []string{"tcp", "tcp4", "tcp6"},
-	ParseNetAddr:     parseTcpNetAddr,
+	ParseNetAddr:     parseTCPNetAddr,
 	ConvertMultiaddr: parseBasicNetMaddr,
 }
 
 var udpAddrSpec = &NetCodec{
 	ProtocolName:     "udp",
 	NetAddrNetworks:  []string{"udp", "udp4", "udp6"},
-	ParseNetAddr:     parseUdpNetAddr,
+	ParseNetAddr:     parseUDPNetAddr,
 	ConvertMultiaddr: parseBasicNetMaddr,
 }
 
 var ip4AddrSpec = &NetCodec{
 	ProtocolName:     "ip4",
 	NetAddrNetworks:  []string{"ip4"},
-	ParseNetAddr:     parseIpNetAddr,
+	ParseNetAddr:     parseIPNetAddr,
 	ConvertMultiaddr: parseBasicNetMaddr,
 }
 
 var ip6AddrSpec = &NetCodec{
 	ProtocolName:     "ip6",
 	NetAddrNetworks:  []string{"ip6"},
-	ParseNetAddr:     parseIpNetAddr,
+	ParseNetAddr:     parseIPNetAddr,
 	ConvertMultiaddr: parseBasicNetMaddr,
 }
 
 var ipnetAddrSpec = &NetCodec{
 	ProtocolName:    "ip+net",
 	NetAddrNetworks: []string{"ip+net"},
-	ParseNetAddr:    parseIpPlusNetAddr,
+	ParseNetAddr:    parseIPPlusNetAddr,
 	ConvertMultiaddr: func(ma.Multiaddr) (net.Addr, error) {
 		return nil, fmt.Errorf("converting ip+net multiaddr not supported")
 	},