Documentation: Clarify some command descriptions

- file(WRITE): add configure_file() decoupling hint
- function(): definitely mention PARENT_SCOPE
- include_directories(): mention possible results of SYSTEM setting
- macro(): mention scope specifics of function()
- message(): improve SEND_ERROR / FATAL_ERROR docs, since people said it's not obvious

Source/cmFileCommand.h

@@ -89,7 +89,8 @@ public:
       "       [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])\n"
       "WRITE will write a message into a file called 'filename'. It "
       "overwrites the file if it already exists, and creates the file "
-      "if it does not exist.\n"
+      "if it does not exist. (If the file is a build input, use "
+      "configure_file to update the file only when its content changes.)\n"
       "APPEND will write a message into a file same as WRITE, except "
       "it will append it to the end of the file\n"
       "READ will read the content of a file and store it into the "

Source/cmFunctionCommand.h

@@ -92,6 +92,8 @@ public:
       "ARGV holds the list of all arguments given to the function and ARGN "
       "holds the list of arguments past the last expected argument."
       "\n"
+      "A function opens a new scope: see set(var PARENT_SCOPE) for details."
+      "\n"
       "See the cmake_policy() command documentation for the behavior of "
       "policies inside functions."
       ;

Source/cmIncludeDirectoryCommand.h

@@ -72,9 +72,12 @@ public:
       "CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. "
       "By using AFTER or BEFORE explicitly, you can select between "
       "appending and prepending, independent of the default. "
+      "\n"
       "If the SYSTEM option is given, the compiler will be told the "
       "directories are meant as system include directories on some "
-      "platforms.";
+      "platforms (signalling this setting might achieve effects such as "
+      "the compiler skipping warnings, or these fixed-install system files "
+      "not being considered in dependency calculations - see compiler docs).";
     }
 
   cmTypeMacro(cmIncludeDirectoryCommand, cmCommand);

Source/cmMacroCommand.h

@@ -95,9 +95,9 @@ public:
       "holds the list of arguments past the last expected argument. "
       "Note that the parameters to a macro and values such as ARGN "
       "are not variables in the usual CMake sense. They are string "
-      "replacements much like the c preprocessor would do with a "
-      "macro. If you want true CMake variables you should look at "
-      "the function command."
+      "replacements much like the C preprocessor would do with a macro. "
+      "If you want true CMake variables and/or better CMake scope control "
+      "you should look at the function command."
       "\n"
       "See the cmake_policy() command documentation for the behavior of "
       "policies inside macros."

Source/cmMessageCommand.h

@@ -67,8 +67,9 @@ public:
       "  STATUS         = Incidental information\n"
       "  WARNING        = CMake Warning, continue processing\n"
       "  AUTHOR_WARNING = CMake Warning (dev), continue processing\n"
-      "  SEND_ERROR     = CMake Error, continue but skip generation\n"
-      "  FATAL_ERROR    = CMake Error, stop all processing\n"
+      "  SEND_ERROR     = CMake Error, continue processing,\n"
+      "                                but skip generation\n"
+      "  FATAL_ERROR    = CMake Error, stop processing and generation\n"
       "The CMake command-line tool displays STATUS messages on stdout "
       "and all other message types on stderr.  "
       "The CMake GUI displays all messages in its log area.  "