Merge pull request #7 from ipfs/docs-improvements

README/docs/travis: improve readme, golint, enable travis

.travis.yml

@@ -0,0 +1,11 @@
+language: go
+go:
+- 'tip'
+install:
+  - go get github.com/whyrusleeping/gx
+  - go get github.com/whyrusleeping/gx-go
+  - gx install --global
+  - gx-go rewrite
+script:
+  - go test -v
+

README.md

@@ -5,9 +5,11 @@
 [![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](http://webchat.freenode.net/?channels=%23ipfs)
 [![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
 [![GoDoc](https://godoc.org/github.com/ipfs/go-log?status.svg)](https://godoc.org/github.com/ipfs/go-log)
-[![Coverage Status](https://coveralls.io/repos/github/ipfs/go-log/badge.svg?branch=master)](https://coveralls.io/github/ipfs/go-log?branch=master)
 [![Build Status](https://travis-ci.org/ipfs/go-log.svg?branch=master)](https://travis-ci.org/ipfs/go-log)
 
+<!---[![Coverage Status](https://coveralls.io/repos/github/ipfs/go-log/badge.svg?branch=master)](https://coveralls.io/github/ipfs/go-log?branch=master)--->
+
+
 > The logging library used by go-ipfs
 
 It currently uses a modified version of [go-logging](https://github.com/whyrusleeping/go-logging) to implement the standard printf-style log output.
@@ -22,9 +24,10 @@ go get github.com/ipfs/go-log
 
 Once the pacakge is imported under the name `logging`, an instance of `EventLogger` can be created like so:
 
-````go
+```go
 var log = logging.Logger("subsystem name")
 ```
+
 It can then be used to emit log messages, either plain printf-style messages at six standard levels or structured messages using `Event` and `EventBegin` methods.
 
 ## Contribute

context.go

@@ -25,6 +25,7 @@ func ContextWithLoggable(ctx context.Context, l Loggable) context.Context {
 	return child
 }
 
+// MetadataFromContext extracts Matadata from a given context's value.
 func MetadataFromContext(ctx context.Context) (Metadata, error) {
 	value := ctx.Value(metadataKey)
 	if value != nil {

log.go

@@ -1,3 +1,6 @@
+// Package log is the logging library used by IPFS
+// (https://github.com/ipfs/go-ipfs). It uses a modified version of
+// https://godoc.org/github.com/whyrusleeping/go-logging .
 package log
 
 import (
@@ -135,6 +138,7 @@ func (el *eventLogger) Event(ctx context.Context, event string, metadata ...Logg
 	WriterGroup.Write(append(out, '\n'))
 }
 
+// EventInProgress represent and event which is happening
 type EventInProgress struct {
 	loggables []Loggable
 	doneFunc  func([]Loggable)
@@ -164,6 +168,7 @@ func (eip *EventInProgress) Close() error {
 	return nil
 }
 
+// FormatRFC3339 returns the given time in UTC with RFC3999Nano format.
 func FormatRFC3339(t time.Time) string {
 	return t.UTC().Format(time.RFC3339Nano)
 }

loggable.go

@@ -5,19 +5,26 @@ type Loggable interface {
 	Loggable() map[string]interface{}
 }
 
+// LoggableMap is just a generic map keyed by string. It
+// implements the Loggable interface.
 type LoggableMap map[string]interface{}
 
+// Loggable implements the Loggable interface for LoggableMap
 func (l LoggableMap) Loggable() map[string]interface{} {
 	return l
 }
 
 // LoggableF converts a func into a Loggable
 type LoggableF func() map[string]interface{}
 
+// Loggable implements the Loggable interface by running
+// the LoggableF function.
 func (l LoggableF) Loggable() map[string]interface{} {
 	return l()
 }
 
+// Deferred returns a LoggableF where the execution of the
+// provided function is deferred.
 func Deferred(key string, f func() string) Loggable {
 	function := func() map[string]interface{} {
 		return map[string]interface{}{
@@ -27,6 +34,7 @@ func Deferred(key string, f func() string) Loggable {
 	return LoggableF(function)
 }
 
+// Pair returns a Loggable where key is paired to Loggable.
 func Pair(key string, l Loggable) Loggable {
 	return LoggableMap{
 		key: l,

metadata.go

@@ -47,19 +47,20 @@ func DeepMerge(b, a Metadata) Metadata {
 	return out
 }
 
-// Loggable implements the Loggable interface
+// Loggable implements the Loggable interface.
 func (m Metadata) Loggable() map[string]interface{} {
 	// NB: method defined on value to avoid de-referencing nil Metadata
 	return m
 }
 
+// JsonString returns the marshaled JSON string for the metadata.
 func (m Metadata) JsonString() (string, error) {
 	// NB: method defined on value
 	b, err := json.Marshal(m)
 	return string(b), err
 }
 
-// Metadatify converts maps into Metadata
+// Metadatify converts maps into Metadata.
 func Metadatify(i interface{}) (Metadata, error) {
 	value := reflect.ValueOf(i)
 	if value.Kind() == reflect.Map {

oldlog.go

@@ -15,6 +15,7 @@ func init() {
 var ansiGray = "\033[0;37m"
 var ansiBlue = "\033[0;34m"
 
+// LogFormats defines formats for logging (i.e. "color")
 var LogFormats = map[string]string{
 	"nocolor": "%{time:2006-01-02 15:04:05.000000} %{level} %{module} %{shortfile}: %{message}",
 	"color": ansiGray + "%{time:15:04:05.000} %{color}%{level:5.5s} " + ansiBlue +

option.go

@@ -6,9 +6,10 @@ import (
 	logging "github.com/whyrusleeping/go-logging"
 )
 
-// Global writer group for logs to output to
+// WriterGroup is the global writer group for logs to output to
 var WriterGroup = NewMirrorWriter()
 
+// Option is a generic function
 type Option func()
 
 // Configure applies the provided options sequentially from left to right
@@ -28,6 +29,8 @@ var TextFormatter = func() {
 	logging.SetFormatter(logging.DefaultFormatter)
 }
 
+// Output returns an option which sets the the given writer as the new
+// logging backend
 func Output(w io.Writer) Option {
 	return func() {
 		backend := logging.NewLogBackend(w, "", 0)

polite_json_formatter.go

@@ -11,6 +11,7 @@ import (
 // overwriting user-provided keys). How polite of it!
 type PoliteJSONFormatter struct{}
 
+// Format encodes a logging.Record in JSON and writes it to Writer.
 func (f *PoliteJSONFormatter) Format(calldepth int, r *logging.Record, w io.Writer) error {
 	entry := make(map[string]interface{})
 	entry["id"] = r.Id

writer.go

@@ -6,10 +6,14 @@ import (
 	"sync"
 )
 
+// MaxWriterBuffer specifies how big the writer buffer can get before
+// killing the writer.
 var MaxWriterBuffer = 512 * 1024
 
 var log = Logger("eventlog")
 
+// MirrorWriter implements a WriteCloser which syncs incoming bytes to multiple
+// [buffered] WriteClosers. They can be added with AddWriter().
 type MirrorWriter struct {
 	active   bool
 	activelk sync.Mutex
@@ -29,6 +33,7 @@ type writerSync struct {
 	br chan []byte
 }
 
+// NewMirrorWriter initializes and returns a MirrorWriter.
 func NewMirrorWriter() *MirrorWriter {
 	mw := &MirrorWriter{
 		msgSync:   make(chan []byte, 64), // sufficiently large buffer to avoid callers waiting
@@ -40,13 +45,15 @@ func NewMirrorWriter() *MirrorWriter {
 	return mw
 }
 
+// Write broadcasts the written bytes to all Writers.
 func (mw *MirrorWriter) Write(b []byte) (int, error) {
 	mycopy := make([]byte, len(b))
 	copy(mycopy, b)
 	mw.msgSync <- mycopy
 	return len(b), nil
 }
 
+// Close closes the MirrorWriter
 func (mw *MirrorWriter) Close() error {
 	// it is up to the caller to ensure that write is not called during or
 	// after close is called.
@@ -126,6 +133,8 @@ type writerAdd struct {
 	done chan struct{}
 }
 
+// AddWriter attaches a new WriteCloser to this MirrorWriter.
+// The new writer will start getting any bytes written to the mirror.
 func (mw *MirrorWriter) AddWriter(w io.WriteCloser) {
 	wa := &writerAdd{
 		w:    w,
@@ -135,6 +144,8 @@ func (mw *MirrorWriter) AddWriter(w io.WriteCloser) {
 	<-wa.done
 }
 
+// Active returns if there is at least one Writer
+// attached to this MirrorWriter
 func (mw *MirrorWriter) Active() (active bool) {
 	mw.activelk.Lock()
 	active = mw.active
@@ -152,6 +163,8 @@ func newBufWriter(w io.WriteCloser) *bufWriter {
 	return bw
 }
 
+// writes incoming messages to a buffer and when it fills
+// up, writes them to the writer
 type bufWriter struct {
 	writer io.WriteCloser