Merge pull request #50 from multiformats/docs-improvements

README/golint: improve example, link to godoc, make golint happy

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-multihash?status.svg)](https://godoc.org/github.com/multiformats/go-multihash)
 [![Travis CI](https://img.shields.io/travis/multiformats/go-multihash.svg?style=flat-square&branch=master)](https://travis-ci.org/multiformats/go-multihash)
 [![codecov.io](https://img.shields.io/codecov/c/github/multiformats/go-multihash.svg?style=flat-square&branch=master)](https://codecov.io/github/multiformats/go-multihash?branch=master)
 
@@ -19,42 +20,76 @@
 
 ## Install
 
+`go-multihash` is a standard Go module which can be installed with:
+
 ```sh
 go get github.com/multiformats/go-multihash
 ```
 
+Note that `go-multihash` 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 it is recommended that you:
+
+```sh
+go get -u github.com/whyrusleeping/gx
+go get -u github.com/whyrusleeping/gx-go
+cd <your-project-repository>
+gx init
+gx import https://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 takes a standard hex-encoded data and uses `EncodeName` to calculate the SHA1 multihash value for the buffer.
+
+The resulting hex-encoded data corresponds to: `<hash function code><digest size><hash function output>`, which could be re-parsed
+with `Multihash.FromHexString()`.
+
+
 ```go
 package main
 
 import (
-  "encoding/hex"
-  "fmt"
-  "github.com/multiformats/go-multihash"
+	"encoding/hex"
+	"fmt"
+
+	"github.com/multiformats/go-multihash"
 )
 
 func main() {
-  // ignores errors for simplicity.
-  // don't do that at home.
-
-  buf, _ := hex.DecodeString("0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33")
-  mhbuf, _ := multihash.EncodeName(buf, "sha1");
-  mhhex := hex.EncodeToString(mhbuf)
-  fmt.Printf("hex: %v\n", mhhex);
-
-  o, _ := multihash.Decode(mhbuf);
-  mhhex = hex.EncodeToString(o.Digest);
-  fmt.Printf("obj: %v 0x%x %d %s\n", o.Name, o.Code, o.Length, mhhex);
+	// ignores errors for simplicity.
+	// don't do that at home.
+	// Decode a SHA1 hash to a binary buffer
+	buf, _ := hex.DecodeString("0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33")
+
+	// Create a new multihash with it.
+	mHashBuf, _ := multihash.EncodeName(buf, "sha1")
+	// Print the multihash as hex string
+	fmt.Printf("hex: %s\n", hex.EncodeToString(mHashBuf))
+
+	// Parse the binary multihash to a DecodedMultihash
+	mHash, _ := multihash.Decode(mHashBuf)
+	// Convert the sha1 value to hex string
+	sha1hex := hex.EncodeToString(mHash.Digest)
+	// Print all the information in the multihash
+	fmt.Printf("obj: %v 0x%x %d %s\n", mHash.Name, mHash.Code, mHash.Length, sha1hex)
 }
 ```
 
-Run [test/foo.go](test/foo.go)
+To run, copy to [example/foo.go](example/foo.go) and:
 
 ```
-> cd test/
+> cd example/
 > go build
-> ./test
+> ./example
 hex: 11140beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
 obj: sha1 0x11 20 0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
 ```

multihash.go

@@ -1,3 +1,6 @@
+// Package multihash is the Go implementation of
+// https://github.com/multiformats/multihash, or self-describing
+// hashes.
 package multihash
 
 import (
@@ -126,23 +129,31 @@ func uvarint(buf []byte) (uint64, []byte, error) {
 	}
 }
 
+// DecodedMultihash represents a parsed multihash and allows
+// easy access to the different parts of a multihash.
 type DecodedMultihash struct {
 	Code   uint64
 	Name   string
-	Length int // Length is just int as it is type of len() opearator
-	Digest []byte
+	Length int    // Length is just int as it is type of len() opearator
+	Digest []byte // Digest holds the raw multihash bytes
 }
 
+// Multihash is byte slice with the following form:
+// <hash function code><digest size><hash function output>.
+// See the spec for more information.
 type Multihash []byte
 
+// HexString returns the hex-encoded representation of a multihash.
 func (m *Multihash) HexString() string {
 	return hex.EncodeToString([]byte(*m))
 }
 
+// String is an alias to HexString().
 func (m *Multihash) String() string {
 	return m.HexString()
 }
 
+// FromHexString parses a hex-encoded multihash.
 func FromHexString(s string) (Multihash, error) {
 	b, err := hex.DecodeString(s)
 	if err != nil {
@@ -152,10 +163,12 @@ func FromHexString(s string) (Multihash, error) {
 	return Cast(b)
 }
 
+// B58String returns the B58-encoded representation of a multihash.
 func (m Multihash) B58String() string {
 	return b58.Encode([]byte(m))
 }
 
+// FromB58String parses a B58-encoded multihash.
 func FromB58String(s string) (m Multihash, err error) {
 	// panic handler, in case we try accessing bytes incorrectly.
 	defer func() {
@@ -174,6 +187,8 @@ func FromB58String(s string) (m Multihash, err error) {
 	return Cast(b)
 }
 
+// Cast casts a buffer onto a multihash, and returns an error
+// if it does not work.
 func Cast(buf []byte) (Multihash, error) {
 	dm, err := Decode(buf)
 	if err != nil {
@@ -187,7 +202,7 @@ func Cast(buf []byte) (Multihash, error) {
 	return Multihash(buf), nil
 }
 
-// Decode a hash from the given Multihash.
+// Decode parses multihash bytes into a DecodedMultihash.
 func Decode(buf []byte) (*DecodedMultihash, error) {
 
 	if len(buf) < 3 {
@@ -242,6 +257,8 @@ func Encode(buf []byte, code uint64) ([]byte, error) {
 	return append(start[:n], buf...), nil
 }
 
+// EncodeName is like Encode() but providing a string name
+// instead of a numeric code. See Names for allowed values.
 func EncodeName(buf []byte, name string) ([]byte, error) {
 	return Encode(buf, Names[name])
 }

sum.go

@@ -14,8 +14,12 @@ import (
 	keccak "leb.io/hashland/keccakpg"
 )
 
+// ErrSumNotSupported is returned when the Sum function code is not implemented
 var ErrSumNotSupported = errors.New("Function not implemented. Complain to lib maintainer.")
 
+// Sum obtains the cryptographic sum of a given buffer. The length parameter
+// indicates the length of the resulting digest and passing a negative value
+// use default length values for the selected hash function.
 func Sum(data []byte, code uint64, length int) (Multihash, error) {
 	m := Multihash{}
 	err := error(nil)