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>

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