Skip to content
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.

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

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

Open
cespare opened this issue Jul 30, 2019 · 20 comments

Comments

@cespare
Copy link
Contributor

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 this to the Go1.13 milestone Jul 30, 2019

@cespare

This comment has been minimized.

Copy link
Contributor Author

commented Jul 30, 2019

This is related to #31716.

@cespare

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Member

commented Jul 31, 2019

@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

This comment has been minimized.

Copy link
Contributor

commented Jul 31, 2019

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

@nsajko

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

commented Aug 1, 2019

I'll take this.

@jba

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Contributor

commented Aug 1, 2019

wiki package

"wiki page"

@jba

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link

commented Aug 2, 2019

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

@jba

This comment has been minimized.

Copy link
Contributor

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

errors: improve doc
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

This comment has been minimized.

Copy link

commented Aug 13, 2019

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

This comment has been minimized.

Copy link

commented Aug 13, 2019

@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

This comment has been minimized.

Copy link
Contributor

commented Aug 13, 2019

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

@gopherbot

This comment has been minimized.

Copy link

commented Aug 22, 2019

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

@jba

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member

commented Aug 22, 2019

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.