code review 8171044: cmd/go: document usage of external test packages

cmd/go: document usage of external test packages

Fixes issue 5144

[kisielk, 2013-03-29 21:01:15]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go

[r, 2013-03-29 21:04:33]

https://codereview.appspot.com/8171044/diff/4002/src/pkg/testing/testing.go
File src/pkg/testing/testing.go (right):

https://codereview.appspot.com/8171044/diff/4002/src/pkg/testing/testing.go#n...
src/pkg/testing/testing.go:14: // Tests may also be declared in external test
packages. If the test package name ends
s/external test packages/separate test packages in the same directory/
and clean up the text that follows from there.

[kisielk, 2013-03-29 22:07:11]

Hello golang-dev@googlegroups.com, r@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r, 2013-03-29 22:15:18]

https://codereview.appspot.com/8171044/diff/14001/src/pkg/testing/testing.go
File src/pkg/testing/testing.go (right):

https://codereview.appspot.com/8171044/diff/14001/src/pkg/testing/testing.go#...
src/pkg/testing/testing.go:12: // in which case they can access all identifiers
in the package.
well, no. they can't access variables local to functions. explaining this so
it's both correct and helpful is hard, so i suggest just dropping everything
after the comma. if you don't know what it means to be in the same package,
trying to explain it here won't help.

https://codereview.appspot.com/8171044/diff/14001/src/pkg/testing/testing.go#...
src/pkg/testing/testing.go:16: // by ``go build'' but recognized by ``go test''.
s/.$/ and be compiled with the main package for the test./

https://codereview.appspot.com/8171044/diff/14001/src/pkg/testing/testing.go#...
src/pkg/testing/testing.go:18: // exported identifiers.
this is a truism for go code. delete.

[kisielk, 2013-03-30 03:38:20]

Hello golang-dev@googlegroups.com, r@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[dave_cheney.net, 2013-03-30 05:52:30]

Here is a not very good attempt at matching the pity style of this package's
comments.

https://codereview.appspot.com/8171044/diff/22001/src/pkg/testing/testing.go
File src/pkg/testing/testing.go (right):

https://codereview.appspot.com/8171044/diff/22001/src/pkg/testing/testing.go#...
src/pkg/testing/testing.go:15: // by ``go build'' but recognized by ``go test''
and compiled with the main package
Suggestion

// Additional tests may also be placed into ```_test.go``` files in the same 
// directory using a package declaration including the suffix ```_test```.
// These are called external tests, and can be useful for breaking dependency
// cycles, or for black box testing.
//
// External tests do not occupy the same package namespace as internal tests
// so must ```import``` the package under test directory, and have no access too
// unexported symbols.

[dave_cheney.net, 2013-03-30 05:52:44]

> Here is a not very good attempt at matching the pity style of this package's
> comments.

err. pithy.

[r, 2013-03-30 14:25:42]

https://codereview.appspot.com/8171044/diff/22001/src/pkg/testing/testing.go
File src/pkg/testing/testing.go (right):

https://codereview.appspot.com/8171044/diff/22001/src/pkg/testing/testing.go#...
src/pkg/testing/testing.go:15: // by ``go build'' but recognized by ``go test''
and compiled with the main package
i'm starting to think that other than the first sentence listed here, most of
this information, however presented, belongs in 'go help test', which tells you
how to construct a test as opposed to how the testing package works.

[kisielk, 2013-04-05 03:09:30]

Agreed, documenting it in testing was barking up the wrong tree.

I think a mention in "go test" docs is more suitable.

PTAL

[adg, 2013-04-08 04:41:49]

LGTM

[adg, 2013-04-08 04:42:13]

*** Submitted as https://code.google.com/p/go/source/detail?r=b7fb7733b29b ***

cmd/go: document usage of external test packages

Fixes issue 5144

R=golang-dev, r, dave, adg
CC=golang-dev
https://codereview.appspot.com/8171044

Committer: Andrew Gerrand <adg@golang.org>

[khr, 2013-07-22 18:00:53]

On 2013/04/08 04:42:13, adg wrote:
> *** Submitted as https://code.google.com/p/go/source/detail?r=b7fb7733b29b ***
> 
> cmd/go: document usage of external test packages
> 
> Fixes issue 5144
> 
> R=golang-dev, r, dave, adg
> CC=golang-dev
> https://codereview.appspot.com/8171044
> 
> Committer: Andrew Gerrand <mailto:adg@golang.org>

R=close

[khr, 2013-07-22 19:24:45]

R=close