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
Labels
Documentation FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@katiehockman
Copy link
Contributor

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

@katiehockman katiehockman added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Apr 10, 2020
@katiehockman katiehockman added this to the Go1.15 milestone Apr 10, 2020
@gopherbot
Copy link

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

@jba
Copy link
Contributor

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

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

@FiloSottile
Copy link
Contributor

@dmitshur, is this a godoc bug?

@antong
Copy link
Contributor

antong commented Apr 13, 2020

Is this a consequence of #38376 ?

@dmitshur
Copy link
Contributor

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
Contributor

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>
@golang golang locked and limited conversation to collaborators Apr 13, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

6 participants