From: Jonathan Amsterdam <jba@google.com>
Date: Mon, 5 Aug 2019 14:14:40 +0000 (-0400)
Subject: doc/go1.13.html: describe error-value additions
X-Git-Tag: go1.13rc1~34
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=a4c825156d0a3817377a2b7e5b30ab50e11440ab;p=gostls13.git

doc/go1.13.html: describe error-value additions

A brief description at the top the Standard Library section of the
changes to support error wrapping.

Fixes #33365.

Change-Id: Id5a3b2fe148d9bfb949f2cfc9e5d8a1613a0e219
Reviewed-on: https://go-review.googlesource.com/c/go/+/188798
Reviewed-by: Ian Lance Taylor <iant@golang.org>
---

diff --git a/doc/go1.13.html b/doc/go1.13.html
index bc44531133..f38474b327 100644
--- a/doc/go1.13.html
+++ b/doc/go1.13.html
@@ -525,6 +525,37 @@ godoc
   <code>crypto/ed25519</code> when used with Go 1.13+.
 </p>
 
+<h3 id="error_wrapping">Error wrapping</h3>
+
+<p><!-- CL 163558, 176998 -->
+  Go 1.13 contains support for error wrapping, as first proposed in
+  the <a href="https://go.googlesource.com/proposal/+/master/design/29934-error-values.md">
+  Error Values proposal</a> and discussed on <a href="https://golang.org/issue/29934">the
+  associated issue</a>.
+</p>
+<p>
+  An error <code>e</code> can <em>wrap</em> another error <code>w</code> by providing
+  an <code>Unwrap</code> method that returns <code>w</code>. Both <code>e</code>
+  and <code>w</code> are available to programs, allowing <code>e</code> to provide
+  additional context to <code>w</code> or to reinterpret it while still allowing
+  programs to make decisions based on <code>w</code>.
+</p>
+<p>
+  To support wrapping, <a href="#fmt"><code>fmt.Errorf</code></a> now has a <code>%w</code>
+  verb for creating wrapped errors, and three new functions in
+  the <a href="#errors"><code>errors</code></a> package (
+  <a href="/pkg/errors#Unwrap"><code>errors.Unwrap</code></a>,
+  <a href="/pkg/errors#Is"><code>errors.Is</code></a> and
+  <a href="/pkg/errors#As"><code>errors.As</code></a>) simplify unwrapping
+  and inspecting wrapped errors.
+</p>
+<p>
+  For more information, read the <a href="/pkg/errors/"><code>errors</code> package
+  documentation</a>, or see
+  the <a href="https://golang.org/wiki/ErrorValueFAQ">Error Value FAQ</a>.
+  There will soon be a blog post as well.
+</p>
+
 <h3 id="minor_library_changes">Minor changes to the library</h3>
 
 <p>
@@ -612,7 +643,8 @@ godoc
   <dd>
     <!-- CL 163558 -->
     <p>
-      The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first error in a given error’s chain
+      The new function <a href="/pkg/errors/#As"><code>As</code></a> finds the first
+      error in a given error’s chain (sequence of wrapped errors)
       that matches a given target’s type, and if so, sets the target to that error value.
     </p>
     <p>