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

1 files changed, 4 insertions, 1 deletions

diff --git a/Source/cmIncludeDirectoryCommand.h b/Source/cmIncludeDirectoryCommand.h
index 6751fc0..dd37b82 100644
--- a/Source/cmIncludeDirectoryCommand.h
+++ b/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);