Start comments with the name of the element it describes

Makefile

@@ -21,4 +21,4 @@ check-go:
 
 docs:
 	godoc2md github.com/juju/errors > README.md
-	sed -i 's|\[godoc-link-here\]|[![GoDoc](https://godoc.org/github.com/juju/errors?status.svg)](https://godoc.org/github.com/juju/errors)|' README.md 
+	sed -i '5i[\[GoDoc](https://godoc.org/github.com/juju/errors?status.svg)](https://godoc.org/github.com/juju/errors)' README.md 

doc.go

@@ -2,9 +2,7 @@
 // Licensed under the LGPLv3, see LICENCE file for details.
 
 /*
-[godoc-link-here]
-
-The juju/errors provides an easy way to annotate errors without losing the
+Package errors provides an easy way to annotate errors without losing the
 original error context.
 
 The exported `New` and `Errorf` functions are designed to replace the

error.go

@@ -90,7 +90,7 @@ func (e *Err) Underlying() error {
 	return e.previous
 }
 
-// The Cause of an error is the most recent error in the error stack that
+// Cause returns the most recent error in the error stack that
 // meets one of these criteria: the original error that was raised; the new
 // error that was passed into the Wrap function; the most recently masked
 // error; or nil if the error itself is considered the Cause.  Normally this

functions.go

@@ -152,7 +152,7 @@ func Wrapf(other, newDescriptive error, format string, args ...interface{}) erro
 	return err
 }
 
-// Mask masks the given error with the given format string and arguments (like
+// Maskf masks the given error with the given format string and arguments (like
 // fmt.Sprintf), returning a new error that maintains the error stack, but
 // hides the underlying error type.  The error string still contains the full
 // annotations. If you want to hide the annotations, call Wrap.