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.

1 files changed, 23 insertions, 0 deletions

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)
+	}
+}