STYLE: extend documentation for RETURN() a bit

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

Alex

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.";
     }
   

Tests/ReturnTest/CMakeLists.txt

@@ -84,6 +84,14 @@ else ("${subdirResult}" EQUAL 1)
   failed ("subdir got: ${subdirResult}")
 endif ("${subdirResult}" EQUAL 1)
 
+# check return from a file
+include(include_return.cmake)
+if ("${include_returnResult}" EQUAL 1)
+  pass ("include_return")
+else ("${include_returnResult}" EQUAL 1)
+  failed ("include_return got: ${include_returnResult}")
+endif ("${include_returnResult}" EQUAL 1)
+
 # check return from within a macro
 macro (mymacro)
   set (foo 1)

Tests/ReturnTest/include_return.cmake

@@ -0,0 +1,3 @@
+set(include_returnResult 1)
+return()
+set(include_returnResult 0)