code review 7206049: go/build: document blank line required after build cons...

src/pkg/go/build/doc.go

 // Copyright 2011 The Go Authors.  All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // Package build gathers information about Go packages.
 //
 // Go Path
 //
 // The Go path is a list of directory trees containing Go source code.
 // It is consulted to resolve imports that cannot be found in the standard
@@ skipping 45 matching lines @@
 //                      bar.a          (installed package object)
 //
 // Build Constraints
 //
 // A build constraint is a line comment beginning with the directive +build
 // that lists the conditions under which a file should be included in the package.
 // Constraints may appear in any kind of source file (not just Go), but
 // they must appear near the top of the file, preceded
 // only by blank lines and other line comments.
 //
+// To distinguish build constraints from package documentation, a blank line

[adg, 2013/01/24 02:19:48]

... a series of build constraints must be followed by a blank line.

[rick, 2013/01/24 02:24:04]

Done.

+// must follow the final build constraint.
+//
 // A build constraint is evaluated as the OR of space-separated options;
 // each option evaluates as the AND of its comma-separated terms;
 // and each term is an alphanumeric word or, preceded by !, its negation.
 // That is, the build constraint:
 //
 //      // +build linux,386 darwin,!cgo
 //
 // corresponds to the boolean formula:
 //
 //      (linux AND 386) OR (darwin AND (NOT cgo))
@@ skipping 35 matching lines @@
 // default functionality for other systems, which in this case would
 // carry the constraint:
 //
 //      // +build !linux,!darwin !cgo
 //
 // Naming a file dns_windows.go will cause it to be included only when
 // building the package for Windows; similarly, math_386.s will be included
 // only when building the package for 32-bit x86.
 //
 package build