STYLE: extend documentation for RETURN() a bit

ENH: add a test for calling RETURN() in an included file

Alex

1 files changed, 9 insertions, 5 deletions

diff --git a/Source/cmReturnCommand.h b/Source/cmReturnCommand.h
index d75cda5295..5aee88b18c 100644
--- a/Source/cmReturnCommand.h
+++ b/Source/cmReturnCommand.h
@@ -57,7 +57,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Return from a directory or function.";
+    return "Return from a file, directory or function.";
     }
   
   /**
@@ -67,10 +67,14 @@ public:
     {
     return
       "  return()\n"
-      "Returns from a directory or function. When this command is "
-      "encountered, it caused process of the current function or "
-      "directory to stop and control is return to the caller of the "
-      "function, or the parent directory if any. Note that a macro "
+      "Returns from a file, directory or function. When this command is "
+      "encountered in an included file (via include() or find_package()), "
+      "it causes processing of the current file to stop and control is "
+      "returned to the including file. If it is encountered in a file which "
+      "is not included by another file, e.g. a CMakeLists.txt, control is "
+      "returned to the parent directory if there is one. "
+      "If return is called in a function, control is returned to the caller "
+      "of the function. Note that a macro "
       "is not a function and does not handle return like a function does.";
     }