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: example code for errors.As has extraneous code #38369

Closed
katiehockman opened this issue Apr 10, 2020 · 7 comments
Closed

errors: example code for errors.As has extraneous code #38369

katiehockman opened this issue Apr 10, 2020 · 7 comments

Comments

@katiehockman
Copy link
Member

@katiehockman katiehockman commented Apr 10, 2020

The example code for errors.As (viewed at https://pkg.go.dev/errors?tab=doc#As) is the entire contents of the wrap_test.go file. It should be just func ExampleAs() { ... } I presume.

In talking this over with @FiloSottile, this may be a more systemic issue which can be improved in godoc. For example, we have the same issue with the chacha20poly1305.NewX example code. However, perhaps we should fix the example for the errors package for now either way.

While we're in there, perhaps we should check if there are any improvements to the documentation for errors as tracked in #31716.

/cc @jba @mpvl

@gopherbot
Copy link

@gopherbot gopherbot commented Apr 11, 2020

Change https://golang.org/cl/227937 mentions this issue: chacha20poly1305: improve ExampleNewX

@jba
Copy link
Contributor

@jba jba commented Apr 12, 2020

The package doc for testing says

The entire test file is presented as the example when it contains a single example function, at least one other function, type, variable, or constant declaration, and no test or benchmark functions.

(Emphasis mine.) The wrap_test.go does have a test function, so the whole file shouldn't be displayed as the example.

So I think this is a bug in the testing package.

@gopherbot
Copy link

@gopherbot gopherbot commented Apr 12, 2020

Change https://golang.org/cl/228038 mentions this issue: errors: add example for Is

@FiloSottile
Copy link
Member

@FiloSottile FiloSottile commented Apr 12, 2020

@dmitshur, is this a godoc bug?

@antong
Copy link
Contributor

@antong antong commented Apr 13, 2020

Is this a consequence of #38376 ?

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Apr 13, 2020

@FiloSottile Yes. @jba's analysis is correct. It's a regression in go/doc package in Go 1.14; filed #38409. Thanks for spotting and reporting.

gopherbot pushed a commit that referenced this issue Apr 13, 2020
Add ExampleIs to illustrate how errors.Is works.

Updates #31716.
Updates #38369.

Change-Id: I1b9a6667614635aa3a5ed8b2c108d8eb6f35748b
Reviewed-on: https://go-review.googlesource.com/c/go/+/228038
Reviewed-by: Damien Neil <dneil@google.com>
@FiloSottile
Copy link
Member

@FiloSottile FiloSottile commented Apr 13, 2020

Looks like this is now tracked in #31716 and #38409.

gopherbot pushed a commit to golang/crypto that referenced this issue Apr 14, 2020
The example was failing to direct users on what to do with the nonce,
which should be almost universally prepended to the ciphertext.

Also, leaving key out of the function was pulling the entire file into
the example.

Updates golang/go#38369

Change-Id: I3a13342fff02e1a5d6f9c4ef2a8bddf0b1097707
Reviewed-on: https://go-review.googlesource.com/c/crypto/+/227937
Run-TryBot: Filippo Valsorda <filippo@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Katie Hockman <katie@golang.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants
You can’t perform that action at this time.