Go: errors: better document Go 1.13 Is/As/Unwrap features

[cespare]

See the current version of the Go 1.13 documentation for the errors package here: https://tip.golang.org/pkg/errors/

If I hadn't read the error values design and related discussion, I think I'd have a hard time understanding the new APIs. Some questions I might have include:

• Is and As documentation refers to "err's chain". What is a chain?
• Is, As, and Unwrap all refer to optional interface methods of the same names. When should errors implement those interfaces?
• What is the relationship between Is, As, and Unwrap?
• As an application developer, how should I be using Is, As, and Unwrap? How about as the author of a package others use?

[cespare]

This is related to #31716.

[cespare]

/cc @jba @neild

[cespare]

@andybons you added a "doc:" prefix, but to be clear, what I'm talking about in this issue is package documentation for the errors package (i.e., changes to .go files), not further documents in the doc/ directory. Other documentation issues (#33185, #32820, and #32303 are recent ones) don't use a doc: prefix.

[andybons]

@cespare got it. Removed.

[katiehockman]

/cc @mpvl @jba any thoughts? Is this something one of you can work on or delegate?

[nsajko]

https://github.com/golang/go/wiki/ErrorValueFAQ answers some of the questions.

[jba]

I'll take this.

[jba]

@nsajko Thanks for reminding me of that. @cespare, to what extent does that FAQ do what you want?

@andybons is it kosher to reference a wiki package from the doc of a standard library package? Would that make sense here?

[cespare]

Thanks @jba!

@nsajko Thanks for reminding me of that. @cespare, to what extent does that FAQ do what you want?

The wiki page is useful, but it is no substitute for package documentation. (And after reading the package documentation, I wouldn't even know that "error values" is the name of the concept.)

@andybons is it kosher to reference a wiki package from the doc of a standard library package? Would that make sense here?

@andybons will correct me if I'm wrong, but I'm quite certain that the policy is that we do not link user-editable wiki pages from package documentation.

I think I useful point of comparison is the context package documentation: that is another package with a small API surface where simply listing the functions doesn't convey the scope or purpose; in order for context to provide full value, the whole ecosystem needs to follow a certain set of conventions about how context is used. The top-level package documentation explains these conventions and uses normative language to push users toward common practices.

[jba]

wiki package

"wiki page"

[jba]

@cespare, I will aim for something like context.

I also found this CL that has been languishing: https://go-review.googlesource.com/c/go/+/184237. I know that's not enough, but if you think it helps and you have +2 power, feel free :)

[andybons]

Don't link to wiki pages from user docs for the reasons @cespare noted above. Anyone in the world can change the info without review.

[gopherbot]

Change https://golang.org/cl/188737 mentions this issue: errors: improve doc

[jba]

https://go-review.googlesource.com/c/go/+/188737.

I deliberately did not address the Is and As _methods_. I think that's another CL.

[jwenz723]

I don't know if this is the best place to mention this, but is it expected that at this time that this example should fail with the error undefined: errors.As?

[changkun]

@jwenz723 the playground service do not have the latest 1.13 beta, that's why it shows the error.

BTW, Go team should offer the playground service with all different versions of Go, including released betas. I am not sure this suggestion was submitted in another issue. @ianlancetaylor

[ianlancetaylor]

The playground discussion should be on a different issue. I don't know of an existing one.

[gopherbot]

Change https://golang.org/cl/191338 mentions this issue: errors: document Is and As methods

[jba]

https://golang.org/cl/191338 attempts to address the Is and As methods. I think a complete effort would involve examples at a minimum, and given the difficulty in getting even https://golang.org/cl/184237 reviewed, that doesn't seem feasible for 1.13.

[andybons]

I don't see any comments on https://golang.org/cl/184237

Is the issue that no one is responding at all?

@neild @mpvl @rsc Can one or all of you please take a look?