doc: improve ioutil.CheckClose doc and example, fix #246.

* Use a proper executable example, instead of one in the comment.

* Improve wording of CheckClose godoc.

2 files changed, 26 insertions, 14 deletions

diff --git a/utils/ioutil/common.go b/utils/ioutil/common.go
index 12ea9eb..73cc9c3 100644
--- a/utils/ioutil/common.go
+++ b/utils/ioutil/common.go
@@ -64,20 +64,9 @@ func WriteNopCloser(w io.Writer) io.WriteCloser {
 	return writeNopCloser{w}
 }
 
-// CheckClose is used with defer to close the given io.Closer and check its
-// returned error value. If Close returns an error and the given *error
-// is not nil, *error is set to the error returned by Close.
-//
-// CheckClose is typically used with named return values like so:
-//
-//   func do(obj *Object) (err error) {
-//     w, err := obj.Writer()
-//     if err != nil {
-//       return nil
-//     }
-//     defer CheckClose(w, &err)
-//     // work with w
-//   }
+// CheckClose calls Close on the given io.Closer. If the given *error points to
+// nil, it will be assigned the error returned by Close. Otherwise, any error
+// returned by Close will be ignored. CheckClose is usually called with defer.
 func CheckClose(c io.Closer, err *error) {
 	if cerr := c.Close(); cerr != nil && *err == nil {
 		*err = cerr
diff --git a/utils/ioutil/common_test.go b/utils/ioutil/common_test.go
index f5017f7..2d6ef80 100644
--- a/utils/ioutil/common_test.go
+++ b/utils/ioutil/common_test.go
@@ -3,6 +3,7 @@ package ioutil
 import (
 	"bytes"
 	"io/ioutil"
+	"strings"
 	"testing"
 
 	. "gopkg.in/check.v1"
@@ -53,3 +54,25 @@ func (s *CommonSuite) TestNewReadCloser(c *C) {
 	c.Assert(r.Close(), IsNil)
 	c.Assert(closer.called, Equals, 1)
 }
+
+func ExampleCheckClose() {
+	// CheckClose is commonly used with named return values
+	f := func() (err error) {
+		// Get a io.ReadCloser
+		r := ioutil.NopCloser(strings.NewReader("foo"))
+
+		// defer CheckClose call with an io.Closer and pointer to error
+		defer CheckClose(r, &err)
+
+		// ... work with r ...
+
+		// if err is not nil, CheckClose will assign any close errors to it
+		return err
+
+	}
+
+	err := f()
+	if err != nil {
+		panic(err)
+	}
+}