From 13d85668ac42525564f04e85f9529d993812f345 Mon Sep 17 00:00:00 2001 From: Andrew Gerrand Date: Tue, 18 Feb 2014 15:53:22 +1100 Subject: [PATCH] go/doc: document the conditions where examples are "playable" LGTM=r R=r CC=golang-codereviews https://golang.org/cl/64910043 --- src/pkg/go/doc/example.go | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/pkg/go/doc/example.go b/src/pkg/go/doc/example.go index 2358ed3890..f4ce9f6541 100644 --- a/src/pkg/go/doc/example.go +++ b/src/pkg/go/doc/example.go @@ -32,6 +32,17 @@ type Example struct { // Examples returns the examples found in the files, sorted by Name field. // The Order fields record the order in which the examples were encountered. +// +// Playable Examples must be in a package whose name ends in "_test". +// An Example is "playable" (the Play field is non-nil) in either of these +// circumstances: +// - The example function is self-contained: the function references only +// identifiers from other packages (or predeclared identifiers, such as +// "int") and the test file does not include a dot import. +// - The entire test file is the example: the file contains exactly one +// example function, zero test or benchmark functions, and at least one +// top-level function, type, variable, or constant declaration other +// than the example function. func Examples(files ...*ast.File) []*Example { var list []*Example for _, file := range files { -- 2.48.1