ENH: Patch from Alex to add IsDiscouraged method for future use in generating separate documentation for old commands. Also modified documentation of MAKE_DIRECTORY and REMOVE commands to indicate they should not be used.

15 files changed, 100 insertions, 2 deletions

diff --git a/Source/cmBuildNameCommand.h b/Source/cmBuildNameCommand.h
index 183b097..174f1f9 100644
--- a/Source/cmBuildNameCommand.h
+++ b/Source/cmBuildNameCommand.h
@@ -72,6 +72,12 @@ public:
       "CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.";
     }
 
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmBuildNameCommand, cmCommand);
 };
 
diff --git a/Source/cmCommand.h b/Source/cmCommand.h
index 7466bb5..55672a6 100644
--- a/Source/cmCommand.h
+++ b/Source/cmCommand.h
@@ -102,6 +102,15 @@ public:
     }
 
   /**
+   * This determines if usage of the method is discouraged or not.
+   * This is currently only used for generating the documentation.
+   */
+  virtual bool IsDiscouraged()
+    {
+    return false;
+    }
+
+  /**
    * The name of the command as specified in CMakeList.txt.
    */
   virtual const char* GetName() = 0;
diff --git a/Source/cmExecProgramCommand.h b/Source/cmExecProgramCommand.h
index 339bda8..64d2f51 100644
--- a/Source/cmExecProgramCommand.h
+++ b/Source/cmExecProgramCommand.h
@@ -88,6 +88,12 @@ public:
       ;
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmExecProgramCommand, cmCommand);
 };
 
diff --git a/Source/cmInstallFilesCommand.h b/Source/cmInstallFilesCommand.h
index 80b1cda..826e5ed 100644
--- a/Source/cmInstallFilesCommand.h
+++ b/Source/cmInstallFilesCommand.h
@@ -94,6 +94,12 @@ public:
       "is stored in the variable CMAKE_INSTALL_PREFIX.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmInstallFilesCommand, cmCommand);
 
 protected:
diff --git a/Source/cmInstallProgramsCommand.h b/Source/cmInstallProgramsCommand.h
index 2cd6d1e..e922af2 100644
--- a/Source/cmInstallProgramsCommand.h
+++ b/Source/cmInstallProgramsCommand.h
@@ -90,6 +90,12 @@ public:
       "is stored in the variable CMAKE_INSTALL_PREFIX.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmInstallProgramsCommand, cmCommand);
 
 protected:
diff --git a/Source/cmInstallTargetsCommand.h b/Source/cmInstallTargetsCommand.h
index 10ab457..ec1d7c8 100644
--- a/Source/cmInstallTargetsCommand.h
+++ b/Source/cmInstallTargetsCommand.h
@@ -72,6 +72,12 @@ public:
       "(Windows DLL), the files will be copied to that directory.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmInstallTargetsCommand, cmCommand);
 };
 
diff --git a/Source/cmLinkLibrariesCommand.h b/Source/cmLinkLibrariesCommand.h
index bd6e80e..2f33689 100644
--- a/Source/cmLinkLibrariesCommand.h
+++ b/Source/cmLinkLibrariesCommand.h
@@ -75,6 +75,12 @@ public:
       "type of build.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmLinkLibrariesCommand, cmCommand);
 };
 
diff --git a/Source/cmMakeDirectoryCommand.h b/Source/cmMakeDirectoryCommand.h
index a25a8d4..7380bcb 100644
--- a/Source/cmMakeDirectoryCommand.h
+++ b/Source/cmMakeDirectoryCommand.h
@@ -60,7 +60,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Create a directory on the file system.";
+    return "Old directory creation command.  Use the FILE command.";
     }
   
   /**
@@ -69,12 +69,21 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
+      "This command has been superceded by the FILE(MAKE_DIRECTORY ...) "
+      "command.  "
+      "It is provided for compatibility with older CMake code.\n"
       "  MAKE_DIRECTORY(directory)\n"
       "Creates the specified directory.  Full paths should be given.  Any "
       "parent directories that do not exist will also be created.  Use with "
       "care.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmMakeDirectoryCommand, cmCommand);
 };
 
diff --git a/Source/cmRemoveCommand.h b/Source/cmRemoveCommand.h
index a1de010..b7ca5a7 100644
--- a/Source/cmRemoveCommand.h
+++ b/Source/cmRemoveCommand.h
@@ -56,7 +56,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Remove a value from a list in a variable.";
+    return "Old list item removal command.  Use the LIST command.";
     }
   
   /**
@@ -65,12 +65,20 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
+      "This command has been superceded by the LIST(REMOVE ...) command.  "
+      "It is provided for compatibility with older CMake code.\n"
       "  REMOVE(VAR VALUE VALUE ...)\n"
       "Removes VALUE from the variable VAR.  "
       "This is typically used to remove entries from a vector "
       "(e.g. semicolon separated list).  VALUE is expanded.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+  
   cmTypeMacro(cmRemoveCommand, cmCommand);
 };
 
diff --git a/Source/cmSubdirCommand.h b/Source/cmSubdirCommand.h
index 71cc31e..4ec3da9 100644
--- a/Source/cmSubdirCommand.h
+++ b/Source/cmSubdirCommand.h
@@ -80,6 +80,12 @@ public:
       "top level project or be built each time make is run from the top.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmSubdirCommand, cmCommand);
 };
 
diff --git a/Source/cmSubdirDependsCommand.h b/Source/cmSubdirDependsCommand.h
index 3e97602..f178443 100644
--- a/Source/cmSubdirDependsCommand.h
+++ b/Source/cmSubdirDependsCommand.h
@@ -67,6 +67,12 @@ public:
       "parallel builds correctly.  This functionality is now automatic.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmSubdirDependsCommand, cmCommand);
 };
 
diff --git a/Source/cmVTKMakeInstantiatorCommand.h b/Source/cmVTKMakeInstantiatorCommand.h
index 377cf75..a8ed52a 100644
--- a/Source/cmVTKMakeInstantiatorCommand.h
+++ b/Source/cmVTKMakeInstantiatorCommand.h
@@ -75,6 +75,12 @@ public:
       "C++ code.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   cmTypeMacro(cmVTKMakeInstantiatorCommand, cmCommand);
   
 protected:
diff --git a/Source/cmVTKWrapJavaCommand.h b/Source/cmVTKWrapJavaCommand.h
index 2532bd2..6ffaa52 100644
--- a/Source/cmVTKWrapJavaCommand.h
+++ b/Source/cmVTKWrapJavaCommand.h
@@ -77,6 +77,12 @@ public:
       "Create Java wrappers for VTK classes.";
     }
   
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
 private:
   std::vector<cmSourceFile> WrapClasses;
   std::vector<std::string> WrapHeaders;
diff --git a/Source/cmVTKWrapPythonCommand.h b/Source/cmVTKWrapPythonCommand.h
index b92b65a..8e58b24 100644
--- a/Source/cmVTKWrapPythonCommand.h
+++ b/Source/cmVTKWrapPythonCommand.h
@@ -77,6 +77,12 @@ public:
       "Create Python wrappers for VTK classes.";
     }
 
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   /**
    * Helper methods
    */
diff --git a/Source/cmVTKWrapTclCommand.h b/Source/cmVTKWrapTclCommand.h
index 77488bc..85c442a 100644
--- a/Source/cmVTKWrapTclCommand.h
+++ b/Source/cmVTKWrapTclCommand.h
@@ -79,6 +79,12 @@ public:
       "Create Tcl wrappers for VTK classes.";
     }
 
+  /** This command is only kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged()
+    {
+    return true;
+    }
+
   /**
    * Helper methods
    */