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 bc44531..f38474b 100644
--- a/doc/go1.13.html
+++ b/doc/go1.13.html
@@ -525,6 +525,37 @@
<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 @@
<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>
