ENH: Document CACHE entry properties

This adds a property documentation section for CACHE properties.
We document the ADVANCED, HELPSTRING, TYPE, and VALUE properties.

Source/cmCacheManager.cxx

@@ -1010,3 +1010,48 @@ bool cmCacheManager::NeedCacheCompatibility(int major, int minor)
   return (actual_compat &&
           actual_compat <= CMake_VERSION_ENCODE(major, minor, 0));
 }
+
+//----------------------------------------------------------------------------
+void cmCacheManager::DefineProperties(cmake *cm)
+{
+  cm->DefineProperty
+    ("ADVANCED", cmProperty::CACHE,
+     "True if entry should be hidden by default in GUIs.",
+     "This is a boolean value indicating whether the entry is considered "
+     "interesting only for advanced configuration.  "
+     "The mark_as_advanced() command modifies this property."
+      );
+
+  cm->DefineProperty
+    ("HELPSTRING", cmProperty::CACHE,
+     "Help associated with entry in GUIs.",
+     "This string summarizes the purpose of an entry to help users set it "
+     "through a CMake GUI."
+      );
+
+  cm->DefineProperty
+    ("TYPE", cmProperty::CACHE,
+     "Widget type for entry in GUIs.",
+     "Cache entry values are always strings, but CMake GUIs present widgets "
+     "to help users set values.  "
+     "The GUIs use this property as a hint to determine the widget type.  "
+     "Valid TYPE values are:\n"
+     "  BOOL          = Boolean ON/OFF value.\n"
+     "  PATH          = Path to a directory.\n"
+     "  FILEPATH      = Path to a file.\n"
+     "  STRING        = Generic string value.\n"
+     "  INTERNAL      = Do not present in GUI at all.\n"
+     "  STATIC        = Value managed by CMake, do not change.\n"
+     "  UNINITIALIZED = Type not yet specified.\n"
+     "Generally the TYPE of a cache entry should be set by the command "
+     "which creates it (set, option, find_library, etc.)."
+      );
+
+  cm->DefineProperty
+    ("VALUE", cmProperty::CACHE,
+     "Value of a cache entry.",
+     "This property maps to the actual value of a cache entry.  "
+     "Setting this property always sets the value without checking, so "
+     "use with care."
+      );
+}

Source/cmCacheManager.h

@@ -155,6 +155,9 @@ public:
   unsigned int GetCacheMinorVersion() { return this->CacheMinorVersion; }
   bool NeedCacheCompatibility(int major, int minor);
 
+  /** Define and document CACHE entry properties.  */
+  static void DefineProperties(cmake *cm);
+
 protected:
   ///! Add an entry into the cache
   void AddCacheEntry(const char* key, const char* value, 

Source/cmDocumentation.cxx

@@ -267,6 +267,7 @@ cmDocumentation::cmDocumentation()
   this->PropertySections.push_back("Properties on Targets");
   this->PropertySections.push_back("Properties on Tests");
   this->PropertySections.push_back("Properties on Source Files");
+  this->PropertySections.push_back("Properties on Cache Entries");
 
   this->VariableSections.push_back("Variables that Provide Information");
   this->VariableSections.push_back("Variables That Change Behavior");

Source/cmake.cxx

@@ -228,6 +228,7 @@ void cmake::InitializeProperties()
   this->PropertyDefinitions.clear();
 
   // initialize properties
+  cmCacheManager::DefineProperties(this);
   cmSourceFile::DefineProperties(this);
   cmTarget::DefineProperties(this);
   cmMakefile::DefineProperties(this);