From 1476686cdb6acafdf62aad7672c3839bc4ca7033 Mon Sep 17 00:00:00 2001
From: Rob Pike <r@golang.org>
Date: Wed, 14 May 2014 13:46:58 -0700
Subject: [PATCH] doc/effective_go.html: a little more about errors Make it a
 little clearer how they are used, in particular that it is not enough just to
 return a nil pointer on error, but also to return an error value explaining
 the problem.

Fixes #1963.

LGTM=bradfitz
R=golang-codereviews, bradfitz
CC=golang-codereviews
https://golang.org/cl/97360045
---
 doc/effective_go.html | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/doc/effective_go.html b/doc/effective_go.html
index aee1c14597..25266d6aba 100644
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -3287,9 +3287,18 @@ the garbage collector for bookkeeping.
 
 <p>
 Library routines must often return some sort of error indication to
-the caller.  As mentioned earlier, Go's multivalue return makes it
+the caller.
+As mentioned earlier, Go's multivalue return makes it
 easy to return a detailed error description alongside the normal
-return value.  By convention, errors have type <code>error</code>,
+return value.
+It is good style to use this feature to provide detailed error information.
+For example, as we'll see, <code>os.Open</code> doesn't
+just return a <code>nil</code> pointer on failure, it also returns an
+error value that describes what went wrong.
+</p>
+
+<p>
+By convention, errors have type <code>error</code>,
 a simple built-in interface.
 </p>
 <pre>
@@ -3301,7 +3310,12 @@ type error interface {
 A library writer is free to implement this interface with a
 richer model under the covers, making it possible not only
 to see the error but also to provide some context.
-For example, <code>os.Open</code> returns an <code>os.PathError</code>.
+As mentioned, alongside the usual <code>*os.File</code>
+return value, <code>os.Open</code> also returns an
+error value.
+If the file is opened successfully, the error will be <code>nil</code>,
+but when there is a problem, it will hold an
+<code>os.PathError</code>:
 </p>
 <pre>
 // PathError records an error and the operation and