ENH: Updated DEFINE_PROPERTY command to be more extendible and more consistent with new SET_PROPERTY and GET_PROPERTY signatures.

1 files changed, 36 insertions, 13 deletions

diff --git a/Source/cmDefinePropertyCommand.h b/Source/cmDefinePropertyCommand.h
index 4f95d46..36c6913 100644
--- a/Source/cmDefinePropertyCommand.h
+++ b/Source/cmDefinePropertyCommand.h
@@ -44,7 +44,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() 
     {
-    return "Define properties used by CMake.";
+    return "Define and document custom properties.";
     }
   
   /**
@@ -53,21 +53,44 @@ public:
   virtual const char* GetFullDocumentation()
     {
       return
-        "  define_property(property_name scope_value\n"
-        "                  short_description\n"
-        "                  full_description inherit)\n"
-        "Define a property for a scope. scope_value is either GLOBAL, "
-        "DIRECTORY, TARGET, TEST, SOURCE_FILE, VARIABLE or CACHED_VARIABLE. "
-        "The short and full descriptions are used to document the property. "
-        "If inherit is TRUE, it will inherit its value from the next more "
-        "global property if it hasn't been set at the specified scope. "
-        "This means that e.g. a TARGET property inherits it's value from the "
-        "DIRECTORY property with the same name if it hasn't been set for the "
-        "target, and then from GLOBAL if it hasn't been set for the directory."
-        ;
+        "  define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |\n"
+        "                   TEST | VARIABLE | CACHED_VARIABLE>\n"
+        "                   PROPERTY <name> [INHERITED]\n"
+        "                   BRIEF_DOCS <brief-doc>\n"
+        "                   FULL_DOCS <full-doc>)\n"
+        "Define one property in a scope for use with the "
+        "set_property and get_property commands.  "
+        "This is primarily useful to associate documentation with property "
+        "names that may be retrieved with the get_property command.  "
+        "The first argument determines the kind of scope in which the "
+        "property should be used.  It must be one of the following:\n"
+        "  GLOBAL    = associated with the global namespace\n"
+        "  DIRECTORY = associated with one directory\n"
+        "  TARGET    = associated with one target\n"
+        "  SOURCE    = associated with one source file\n"
+        "  TEST      = associated with a test named with add_test command\n"
+        "  VARIABLE  = documents a CMake language variable\n"
+        "  CACHED_VARIABLE = documents a CMake cache variable\n"
+        "Note that unlike set_property and get_property no actual scope "
+        "needs to be given; only the kind of scope is important.\n"
+        "The required PROPERTY option is immediately followed by the name "
+        "of the property being defined.\n"
+        "If the INHERITED option then the get_property command will chain "
+        "up to the next higher scope when the requested property is not "
+        "set in the scope given to the command.  "
+        "DIRECTORY scope chains to GLOBAL.  "
+        "TARGET, SOURCE, and TEST chain to DIRECTORY.\n"
+        "The BRIEF_DOCS and FULL_DOCS options are followed by strings to be "
+        "associated with the property as its brief and full documentation.  "
+        "Corresponding options to the get_property command will retrieve the "
+        "documentation.";
     }
   
   cmTypeMacro(cmDefinePropertyCommand, cmCommand);
+private:
+  std::string PropertyName;
+  std::string BriefDocs;
+  std::string FullDocs;
 };