Clarify auto-dereference cases in if() command (#11701)

Show "<variable|string>" explicitly in if() case documentation whenever
auto-dereferencing occurs.  Reference its presence from the explanation
at the bottom.

1 files changed, 14 insertions, 20 deletions

diff --git a/Source/cmIfCommand.h b/Source/cmIfCommand.h
index 7c4baba4e4..4996bc4007 100644
--- a/Source/cmIfCommand.h
+++ b/Source/cmIfCommand.h
@@ -166,32 +166,25 @@ public:
       "Behavior is well-defined only for full paths.\n"
       "  if(IS_ABSOLUTE path)\n"
       "True if the given path is an absolute path.\n"
-      "  if(variable MATCHES regex)\n"
-      "  if(string MATCHES regex)\n"
+      "  if(<variable|string> MATCHES regex)\n"
       "True if the given string or variable's value matches the given "
       "regular expression.\n"
-      "  if(variable LESS number)\n"
-      "  if(string LESS number)\n"
-      "  if(variable GREATER number)\n"
-      "  if(string GREATER number)\n"
-      "  if(variable EQUAL number)\n"
-      "  if(string EQUAL number)\n"
+      "  if(<variable|string> LESS <variable|string>)\n"
+      "  if(<variable|string> GREATER <variable|string>)\n"
+      "  if(<variable|string> EQUAL <variable|string>)\n"
       "True if the given string or variable's value is a valid number and "
       "the inequality or equality is true.\n"
-      "  if(variable STRLESS string)\n"
-      "  if(string STRLESS string)\n"
-      "  if(variable STRGREATER string)\n"
-      "  if(string STRGREATER string)\n"
-      "  if(variable STREQUAL string)\n"
-      "  if(string STREQUAL string)\n"
+      "  if(<variable|string> STRLESS <variable|string>)\n"
+      "  if(<variable|string> STRGREATER <variable|string>)\n"
+      "  if(<variable|string> STREQUAL <variable|string>)\n"
       "True if the given string or variable's value is lexicographically "
       "less (or greater, or equal) than the string or variable on the right.\n"
-      "  if(version1 VERSION_LESS version2)\n"
-      "  if(version1 VERSION_EQUAL version2)\n"
-      "  if(version1 VERSION_GREATER version2)\n"
+      "  if(<variable|string> VERSION_LESS <variable|string>)\n"
+      "  if(<variable|string> VERSION_EQUAL <variable|string>)\n"
+      "  if(<variable|string> VERSION_GREATER <variable|string>)\n"
       "Component-wise integer version number comparison (version format is "
       "major[.minor[.patch[.tweak]]]).\n"
-      "  if(DEFINED variable)\n"
+      "  if(DEFINED <variable>)\n"
       "True if the given variable is defined. It does not matter if the "
       "variable is true or false just if it has been set.\n"
       "  if((expression) AND (expression OR (expression)))\n"
@@ -204,7 +197,7 @@ public:
 
       "The if command was written very early in CMake's history, predating "
       "the ${} variable evaluation syntax, and for convenience evaluates "
-      "variables named by its arguments.  "
+      "variables named by its arguments as shown in the above signatures.  "
       "Note that normal variable evaluation with ${} applies before the "
       "if command even receives the arguments.  "
       "Therefore code like\n"
@@ -221,7 +214,8 @@ public:
       "which is true because var2 is defined to \"var1\" which is not "
       "a false constant."
       "\n"
-      "Automatic evaluation applies in the other cases as follows:\n"
+      "Automatic evaluation applies in the other cases whenever the "
+      "above-documented signature accepts <variable|string>:\n"
 
       "1) The left hand argument to MATCHES is first checked to see "
       "if it is a defined variable, if so the variable's value is "