From: Andrew Gerrand <adg@golang.org>
Date: Tue, 18 Feb 2014 04:53:22 +0000 (+1100)
Subject: go/doc: document the conditions where examples are "playable"
X-Git-Tag: go1.3beta1~671
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=13d85668ac42525564f04e85f9529d993812f345;p=gostls13.git

go/doc: document the conditions where examples are "playable"

LGTM=r
R=r
CC=golang-codereviews
https://golang.org/cl/64910043
---

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 {