Merge pull request #3 from ipfs/docs-improvements

Docs: Improve Readme and make golint happy

README.md

@@ -10,8 +10,26 @@
 
 ## Install
 
+This is a Go module which can be installed with `go get github.com/ipfs/go-ipfs-util`. `go-ipfs-util` is however packaged with Gx, so it is recommended to use Gx to install it (see Usage section).
+
 ## Usage
 
+This module is packaged with [Gx](https://github.com/whyrusleeping/gx).
+In order to use it in your own project do:
+
+```
+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/ipfs/go-ipfs-util
+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.
+
+
 ## Contribute
 
 Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs/go-ipfs-util/issues)!

file.go

@@ -2,6 +2,7 @@ package util
 
 import "os"
 
+// FileExists check if the file with the given path exits.
 func FileExists(filename string) bool {
 	fi, err := os.Lstat(filename)
 	if fi != nil || (err != nil && !os.IsNotExist(err)) {

time.go

@@ -2,8 +2,11 @@ package util
 
 import "time"
 
+// TimeFormatIpfs is the format ipfs uses to represent time in string form.
 var TimeFormatIpfs = time.RFC3339Nano
 
+// ParseRFC3339 parses an RFC3339Nano-formatted time stamp and
+// returns the UTC time.
 func ParseRFC3339(s string) (time.Time, error) {
 	t, err := time.Parse(TimeFormatIpfs, s)
 	if err != nil {
@@ -12,6 +15,8 @@ func ParseRFC3339(s string) (time.Time, error) {
 	return t.UTC(), nil
 }
 
+// FormatRFC3339 returns the string representation of the
+// UTC value of the given time in RFC3339Nano format.
 func FormatRFC3339(t time.Time) string {
 	return t.UTC().Format(TimeFormatIpfs)
 }

util.go

@@ -28,7 +28,7 @@ var ErrNotImplemented = errors.New("Error: not implemented yet.")
 // ErrTimeout implies that a timeout has been triggered
 var ErrTimeout = errors.New("Error: Call timed out.")
 
-// ErrSeErrSearchIncomplete implies that a search type operation didnt
+// ErrSearchIncomplete implies that a search type operation didnt
 // find the expected node, but did find 'a' node.
 var ErrSearchIncomplete = errors.New("Error: Search Incomplete.")
 
@@ -57,6 +57,8 @@ type randGen struct {
 	rand.Rand
 }
 
+// NewTimeSeededRand returns a random bytes reader
+// which has been initialized with the current time.
 func NewTimeSeededRand() io.Reader {
 	src := rand.NewSource(time.Now().UnixNano())
 	return &randGen{
@@ -64,6 +66,8 @@ func NewTimeSeededRand() io.Reader {
 	}
 }
 
+// NewSeededRand returns a random bytes reader
+// initialized with the given seed.
 func NewSeededRand(seed int64) io.Reader {
 	src := rand.NewSource(seed)
 	return &randGen{
@@ -102,6 +106,9 @@ func (m MultiErr) Error() string {
 	return s
 }
 
+// Partition splits a subject 3 parts: prefix, separator, suffix.
+// The first occurrence of the separator will be matched.
+// ie. Partition("Ready, steady, go!", ", ") -> ["Ready", ", ", "steady, go!"]
 func Partition(subject string, sep string) (string, string, string) {
 	if i := strings.Index(subject, sep); i != -1 {
 		return subject[:i], subject[i : i+len(sep)], subject[i+len(sep):]
@@ -109,6 +116,9 @@ func Partition(subject string, sep string) (string, string, string) {
 	return subject, "", ""
 }
 
+// RPartition splits a subject 3 parts: prefix, separator, suffix.
+// The last occurrence of the separator will be matched.
+// ie. RPartition("Ready, steady, go!", ", ") -> ["Ready, steady", ", ", "go!"]
 func RPartition(subject string, sep string) (string, string, string) {
 	if i := strings.LastIndex(subject, sep); i != -1 {
 		return subject[:i], subject[i : i+len(sep)], subject[i+len(sep):]