Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
errors: better document Go 1.13 Is/As/Unwrap features #33364
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:
@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.
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 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.