cmd/cgo: document that #including source files in subdirectories is a bad idea

Suggested in discussion on #26366.

Change-Id: Id9ad2e429a915f88b4c4b30fc415c722eebe0ea4
Reviewed-on: https://go-review.googlesource.com/125297
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/cmd/cgo/doc.go b/src/cmd/cgo/doc.go
index 980906b9212d70c949d4fd3a798de2cebe28092d..157cd94d653abf71214778226ab01ef54e9059ab 100644 (file)
--- a/src/cmd/cgo/doc.go
+++ b/src/cmd/cgo/doc.go
@@ -104,10 +104,13 @@ compiled with the C compiler. Any .cc, .cpp, or .cxx files will be
 compiled with the C++ compiler. Any .f, .F, .for or .f90 files will be
 compiled with the fortran compiler. Any .h, .hh, .hpp, or .hxx files will
 not be compiled separately, but, if these header files are changed,
-the C and C++ files will be recompiled. The default C and C++
-compilers may be changed by the CC and CXX environment variables,
-respectively; those environment variables may include command line
-options.
+the package (including its non-Go source files) will be recompiled.
+Note that changes to files in other directories do not cause the package
+to be recompiled, so all non-Go source code for the package should be
+stored in the package directory, not in subdirectories.
+The default C and C++ compilers may be changed by the CC and CXX
+environment variables, respectively; those environment variables
+may include command line options.
 
 The cgo tool is enabled by default for native builds on systems where
 it is expected to work. It is disabled by default when