|
2 | 2 | // |
3 | 3 | // The traditional error handling idiom in Go is roughly akin to |
4 | 4 | // |
5 | | -// if err != nil { |
6 | | -// return err |
7 | | -// } |
| 5 | +// if err != nil { |
| 6 | +// return err |
| 7 | +// } |
8 | 8 | // |
9 | 9 | // which when applied recursively up the call stack results in error reports |
10 | 10 | // without context or debugging information. The errors package allows |
11 | 11 | // programmers to add context to the failure path in their code in a way |
12 | 12 | // that does not destroy the original value of the error. |
13 | 13 | // |
14 | | -// Adding context to an error |
| 14 | +// # Adding context to an error |
15 | 15 | // |
16 | 16 | // The errors.Wrap function returns a new error that adds context to the |
17 | 17 | // original error by recording a stack trace at the point Wrap is called, |
18 | 18 | // together with the supplied message. For example |
19 | 19 | // |
20 | | -// _, err := ioutil.ReadAll(r) |
21 | | -// if err != nil { |
22 | | -// return errors.Wrap(err, "read failed") |
23 | | -// } |
| 20 | +// _, err := io.ReadAll(r) |
| 21 | +// if err != nil { |
| 22 | +// return errors.Wrap(err, "read failed") |
| 23 | +// } |
24 | 24 | // |
25 | 25 | // If additional control is required, the errors.WithStack and |
26 | 26 | // errors.WithMessage functions destructure errors.Wrap into its component |
27 | 27 | // operations: annotating an error with a stack trace and with a message, |
28 | 28 | // respectively. |
29 | 29 | // |
30 | | -// Retrieving the cause of an error |
| 30 | +// # Retrieving the cause of an error |
31 | 31 | // |
32 | 32 | // Using errors.Wrap constructs a stack of errors, adding context to the |
33 | 33 | // preceding error. Depending on the nature of the error it may be necessary |
34 | 34 | // to reverse the operation of errors.Wrap to retrieve the original error |
35 | 35 | // for inspection. Any error value which implements this interface |
36 | 36 | // |
37 | | -// type causer interface { |
38 | | -// Cause() error |
39 | | -// } |
| 37 | +// type causer interface { |
| 38 | +// Cause() error |
| 39 | +// } |
40 | 40 | // |
41 | 41 | // can be inspected by errors.Cause. errors.Cause will recursively retrieve |
42 | 42 | // the topmost error that does not implement causer, which is assumed to be |
43 | 43 | // the original cause. For example: |
44 | 44 | // |
45 | | -// switch err := errors.Cause(err).(type) { |
46 | | -// case *MyError: |
47 | | -// // handle specifically |
48 | | -// default: |
49 | | -// // unknown error |
50 | | -// } |
| 45 | +// switch err := errors.Cause(err).(type) { |
| 46 | +// case *MyError: |
| 47 | +// // handle specifically |
| 48 | +// default: |
| 49 | +// // unknown error |
| 50 | +// } |
51 | 51 | // |
52 | 52 | // Although the causer interface is not exported by this package, it is |
53 | 53 | // considered a part of its stable public interface. |
54 | 54 | // |
55 | | -// Formatted printing of errors |
| 55 | +// # Formatted printing of errors |
56 | 56 | // |
57 | 57 | // All error values returned from this package implement fmt.Formatter and can |
58 | 58 | // be formatted by the fmt package. The following verbs are supported: |
59 | 59 | // |
60 | | -// %s print the error. If the error has a Cause it will be |
61 | | -// printed recursively. |
62 | | -// %v see %s |
63 | | -// %+v extended format. Each Frame of the error's StackTrace will |
64 | | -// be printed in detail. |
| 60 | +// %s print the error. If the error has a Cause it will be |
| 61 | +// printed recursively. |
| 62 | +// %v see %s |
| 63 | +// %+v extended format. Each Frame of the error's StackTrace will |
| 64 | +// be printed in detail. |
65 | 65 | // |
66 | | -// Retrieving the stack trace of an error or wrapper |
| 66 | +// # Retrieving the stack trace of an error or wrapper |
67 | 67 | // |
68 | 68 | // New, Errorf, Wrap, and Wrapf record a stack trace at the point they are |
69 | 69 | // invoked. This information can be retrieved with the following interface: |
70 | 70 | // |
71 | | -// type stackTracer interface { |
72 | | -// StackTrace() errors.StackTrace |
73 | | -// } |
| 71 | +// type stackTracer interface { |
| 72 | +// StackTrace() errors.StackTrace |
| 73 | +// } |
74 | 74 | // |
75 | 75 | // The returned errors.StackTrace type is defined as |
76 | 76 | // |
77 | | -// type StackTrace []Frame |
| 77 | +// type StackTrace []Frame |
78 | 78 | // |
79 | 79 | // The Frame type represents a call site in the stack trace. Frame supports |
80 | 80 | // the fmt.Formatter interface that can be used for printing information about |
81 | 81 | // the stack trace of this error. For example: |
82 | 82 | // |
83 | | -// if err, ok := err.(stackTracer); ok { |
84 | | -// for _, f := range err.StackTrace() { |
85 | | -// fmt.Printf("%+s:%d\n", f, f) |
86 | | -// } |
87 | | -// } |
| 83 | +// if err, ok := err.(stackTracer); ok { |
| 84 | +// for _, f := range err.StackTrace() { |
| 85 | +// fmt.Printf("%+s:%d\n", f, f) |
| 86 | +// } |
| 87 | +// } |
88 | 88 | // |
89 | 89 | // Although the stackTracer interface is not exported by this package, it is |
90 | 90 | // considered a part of its stable public interface. |
@@ -265,13 +265,18 @@ func (w *withMessage) Format(s fmt.State, verb rune) { |
265 | 265 | // An error value has a cause if it implements the following |
266 | 266 | // interface: |
267 | 267 | // |
268 | | -// type causer interface { |
269 | | -// Cause() error |
270 | | -// } |
| 268 | +// type causer interface { |
| 269 | +// Cause() error |
| 270 | +// } |
271 | 271 | // |
272 | 272 | // If the error does not implement Cause, the original error will |
273 | 273 | // be returned. If the error is nil, nil will be returned without further |
274 | 274 | // investigation. |
| 275 | +// |
| 276 | +// Note: Cause only traverses errors implementing the causer interface. |
| 277 | +// It does not traverse errors wrapped with fmt.Errorf("%w", err) or |
| 278 | +// other standard library mechanisms. Prefer errors.Is or errors.As |
| 279 | +// for matching errors across mixed wrapping styles. |
275 | 280 | func Cause(err error) error { |
276 | 281 | type causer interface { |
277 | 282 | Cause() error |
|
0 commit comments