Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
cespare opened this issue Jul 30, 2019 · 20 comments
Closed

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

cespare opened this issue Jul 30, 2019 · 20 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. release-blocker
Milestone
Go1.13

Comments

@cespare
Copy link
Contributor

cespare commented Jul 30, 2019

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 cespare added Documentation Issues describing a change to documentation. release-blocker labels Jul 30, 2019
@cespare cespare added this to the Go1.13 milestone Jul 30, 2019
@cespare
Copy link
Contributor Author

cespare commented Jul 30, 2019

This is related to #31716.

@cespare cespare mentioned this issue Jul 30, 2019
Closed
@cespare
Copy link
Contributor Author

cespare commented Jul 30, 2019

/cc @jba @neild

@andybons andybons changed the title errors: better document Go 1.13 Is/As/Unwrap features doc: errors: better document Go 1.13 Is/As/Unwrap features Jul 30, 2019
@cespare
Copy link
Contributor Author

cespare commented Jul 31, 2019

@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
Copy link
Member

@cespare got it. Removed.

@andybons andybons changed the title doc: errors: better document Go 1.13 Is/As/Unwrap features errors: better document Go 1.13 Is/As/Unwrap features Jul 31, 2019
@katiehockman
Copy link
Contributor

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

@katiehockman katiehockman added NeedsFix The path to resolution is known, but the work has not been done. NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. and removed NeedsFix The path to resolution is known, but the work has not been done. labels Jul 31, 2019
@nsajko
Copy link
Contributor

nsajko commented Jul 31, 2019

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

@jba jba self-assigned this Aug 1, 2019
@jba
Copy link
Contributor

jba commented Aug 1, 2019

I'll take this.

@jba
Copy link
Contributor

jba commented Aug 1, 2019

@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
Copy link
Contributor Author

cespare commented Aug 1, 2019

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
Copy link
Contributor

jba commented Aug 1, 2019

wiki package

"wiki page"

@jba
Copy link
Contributor

jba commented Aug 1, 2019

@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
Copy link
Member

andybons commented Aug 1, 2019

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
Copy link
Contributor

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

@jba
Copy link
Contributor

jba commented Aug 2, 2019

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

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

gopherbot pushed a commit that referenced this issue Aug 6, 2019
@jba
errors: improve doc
546ea78 
Explain wrapping and how to use Is and As in the package doc.

Explain "chain" in Is and As.

Updates #33364.

Change-Id: Ic06362106dbd129e33dd47e63176ee5355492086
Reviewed-on: https://go-review.googlesource.com/c/go/+/188737
Reviewed-by: Rob Pike <r@golang.org>
@jwenz723
Copy link

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
Copy link
Member

@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
Copy link
Contributor

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

@gopherbot
Copy link
Contributor

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

@jba
Copy link
Contributor

jba commented Aug 22, 2019

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
Copy link
Member

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?

tomocy pushed a commit to tomocy/go that referenced this issue Sep 1, 2019
@jba @tomocy
errors: document Is and As methods
9b190f5 
Add brief descriptions of why one might implement
an Is or As method.

Fixes golang#33364.

Change-Id: I81a091bf564c654ddb9ef3997e780451a01efb7a
Reviewed-on: https://go-review.googlesource.com/c/go/+/191338
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
t4n6a1ka pushed a commit to t4n6a1ka/go that referenced this issue Sep 5, 2019
@jba @t4n6a1ka
errors: document Is and As methods
6a6bac6 
Add brief descriptions of why one might implement
an Is or As method.

Fixes golang#33364.

Change-Id: I81a091bf564c654ddb9ef3997e780451a01efb7a
Reviewed-on: https://go-review.googlesource.com/c/go/+/191338
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@golang golang locked and limited conversation to collaborators Aug 26, 2020
@rsc rsc unassigned jba Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. release-blocker
Projects
None yet
Milestone
Go1.13
Development

No branches or pull requests
9 participants
@cespare @andybons @ianlancetaylor @nsajko @changkun @gopherbot @jwenz723 @jba @katiehockman