ENH: Added warning about using this command to avoid listing sources for a library by hand. It is supposed to be used only for Templates directories.

Source/cmAuxSourceDirectoryCommand.h

@@ -66,7 +66,19 @@ public:
     return
       "  AUX_SOURCE_DIRECTORY(dir VARIABLE)\n"
       "Collects the names of all the source files in the specified "
-      "directory and stores the list in the variable provided.";
+      "directory and stores the list in the variable provided.  This command "
+      "is intended to be used by projects that use explicit template "
+      "instantiation.  Template instantiation files can be stored in a "
+      "\"Templates\" subdirectory and collected automatically using this "
+      "command to avoid manually listing all instantiations.\n"
+      "It is tempting to use this command to avoid writing the list of source "
+      "files for a library or executable target.  While this seems to work, "
+      "there is no way for CMake to generate a build system that knows when a "
+      "new source file has been added.  Normally the generated build system "
+      "knows when it needs to rerun CMake because the CMakeLists.txt file "
+      "is modified to add a new source.  When the source is just added to "
+      "the directory without modifying this file, one would have to manually "
+      "rerun CMake to generate a build system incorporating the new file.";
     }
   
   cmTypeMacro(cmAuxSourceDirectoryCommand, cmCommand);