ENH: Document CACHE entry properties

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

1 files changed, 45 insertions, 0 deletions

diff --git a/Source/cmCacheManager.cxx b/Source/cmCacheManager.cxx
index 365d052..73b523c 100644
--- a/Source/cmCacheManager.cxx
+++ b/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."
+      );
+}