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

testing: test example missing from beginning of package doc #27839

Closed
leighmcculloch opened this issue Sep 25, 2018 · 3 comments

Comments

Projects
None yet
3 participants
@leighmcculloch
Copy link
Contributor

commented Sep 25, 2018

What version of Go are you using (go version)?

go version go1.11

What did you do?

I went to the testing package documentation to find an example to share with another person.

What did you expect to see?

I expected to be see a simple few line example demonstrating how to write a test function and how to write an expectation.

What did you see instead?

Full examples for benchmarks, and example tests, and even an example of how to skip a test, but no examples of how to write a test with a simple expectation.

CL

I can open a small CL adding an example to the package documentation unless anyone feels like that'd be a bad idea.

@gopherbot

This comment has been minimized.

Copy link

commented Sep 25, 2018

Change https://golang.org/cl/137175 mentions this issue: testing: add example to package doc

@leighmcculloch

This comment has been minimized.

Copy link
Contributor Author

commented Sep 25, 2018

Screenshots from the CL ☝️

The example in the beginning section of the overview:

screen shot 2018-09-24 at 10 59 48 pm

The existing skipping example moved to a later section:

screen shot 2018-09-24 at 11 00 02 pm

@andybons

This comment has been minimized.

Copy link
Member

commented Sep 25, 2018

@gopherbot gopherbot closed this in 79257c4 Nov 16, 2018

bradfitz added a commit that referenced this issue Nov 21, 2018

testing: add example to package doc
The package doc for the testing package doesn't have a simple
example demonstrating how to write a test with an expectation. The doc
has simple examples for benchmarks, examples, and skipping, and it would be
useful for people new to writing tests in Go.

Also moved the skip example further down because it references tests and
benchmarks but benchmarks haven't been discussed in detail until the
next section. Skip is also a less used feature and it seems misplaced to
sit so high up in the package documentation. As an example, Skip is used
570 times the Go code repository which is significantly less than Error
and Fatal that are used 23,303 times.

Also changed 'sample' to 'simple' in other places in the package documentation
to keep the language used consistent when describing the small examples.

Fixes #27839

Change-Id: Ie01a3751986ee61adf2a2f2eda59cc182342baa7
GitHub-Last-Rev: 7357bfd
GitHub-Pull-Request: #27840
Reviewed-on: https://go-review.googlesource.com/c/137175
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.