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
Closed

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

leighmcculloch opened this issue Sep 25, 2018 · 3 comments

Comments

@leighmcculloch
Copy link
Contributor

@leighmcculloch leighmcculloch 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

@gopherbot gopherbot 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

@leighmcculloch leighmcculloch 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

@andybons andybons commented Sep 25, 2018

@gopherbot gopherbot closed this in 79257c4 Nov 16, 2018
bradfitz added a commit that referenced this issue Nov 21, 2018
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>
@golang golang locked and limited conversation to collaborators Nov 16, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
3 participants
You can’t perform that action at this time.