From 814b3687251605ed5c2924b0705ebae2e70d2eb3 Mon Sep 17 00:00:00 2001
From: Alexander Neundorf <neundorf@kde.org>
Date: Sat, 16 Aug 2008 18:06:17 -0400
Subject: [PATCH] STYLE: extend documentation for RETURN() a bit ENH: add a
 test for calling RETURN() in an included file

Alex
---
 Source/cmReturnCommand.h              | 14 +++++++++-----
 Tests/ReturnTest/CMakeLists.txt       |  8 ++++++++
 Tests/ReturnTest/include_return.cmake |  3 +++
 3 files changed, 20 insertions(+), 5 deletions(-)
 create mode 100644 Tests/ReturnTest/include_return.cmake

diff --git a/Source/cmReturnCommand.h b/Source/cmReturnCommand.h
index d75cda529..5aee88b18 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.";
     }
   
diff --git a/Tests/ReturnTest/CMakeLists.txt b/Tests/ReturnTest/CMakeLists.txt
index bd0966e01..7c9156bf8 100644
--- a/Tests/ReturnTest/CMakeLists.txt
+++ b/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)
diff --git a/Tests/ReturnTest/include_return.cmake b/Tests/ReturnTest/include_return.cmake
new file mode 100644
index 000000000..7cea1fb2d
--- /dev/null
+++ b/Tests/ReturnTest/include_return.cmake
@@ -0,0 +1,3 @@
+set(include_returnResult 1)
+return()
+set(include_returnResult 0)