Document compiler version macro formats used for detection

The MSVC, HP, XL, SunPro, Watcom, Borland, and Intel compilers specify
their version number in components encoded in a single integer value.
Document the components that we use to compute version numbers.

Modules/CMakeCCompilerId.c.in

@@ -2,16 +2,21 @@
 # error "A C++ compiler has been selected for C."
 #endif
 
+/* Version number components: V=Version, R=Revision, P=Patch
+   Version date components:   YYYY=Year, MM=Month,   DD=Day  */
+
 #if defined(__18CXX)
 # define ID_VOID_MAIN
 #endif
 
 #if defined(__INTEL_COMPILER) || defined(__ICC)
 # define COMPILER_ID "Intel"
+  /* __INTEL_COMPILER = VRP */
 # define COMPILER_VERSION_MAJOR DEC(__INTEL_COMPILER/100)
 # define COMPILER_VERSION_MINOR DEC(__INTEL_COMPILER/10 % 10)
 # define COMPILER_VERSION_PATCH DEC(__INTEL_COMPILER    % 10)
 # if defined(__INTEL_COMPILER_BUILD_DATE)
+  /* __INTEL_COMPILER_BUILD_DATE = YYYYMMDD */
 #  define COMPILER_VERSION_TWEAK DEC(__INTEL_COMPILER_BUILD_DATE)
 # endif
 
@@ -23,21 +28,25 @@
 
 #elif defined(__BORLANDC__)
 # define COMPILER_ID "Borland"
+  /* __BORLANDC__ = 0xVRR */
 # define COMPILER_VERSION_MAJOR HEX(__BORLANDC__>>8)
 # define COMPILER_VERSION_MINOR HEX(__BORLANDC__ & 0xFF)
 
 #elif defined(__WATCOMC__)
 # define COMPILER_ID "Watcom"
+  /* __WATCOMC__ = VVRR */
 # define COMPILER_VERSION_MAJOR DEC(__WATCOMC__ / 100)
 # define COMPILER_VERSION_MINOR DEC(__WATCOMC__ % 100)
 
 #elif defined(__SUNPRO_C)
 # define COMPILER_ID "SunPro"
 # if __SUNPRO_C >= 0x5100
+   /* __SUNPRO_C = 0xVRRP */
 #  define COMPILER_VERSION_MAJOR HEX(__SUNPRO_C>>12)
 #  define COMPILER_VERSION_MINOR HEX(__SUNPRO_C>>4 & 0xFF)
 #  define COMPILER_VERSION_PATCH HEX(__SUNPRO_C    & 0xF)
 # else
+   /* __SUNPRO_C = 0xVRP */
 #  define COMPILER_VERSION_MAJOR HEX(__SUNPRO_C>>8)
 #  define COMPILER_VERSION_MINOR HEX(__SUNPRO_C>>4 & 0xF)
 #  define COMPILER_VERSION_PATCH HEX(__SUNPRO_C    & 0xF)
@@ -45,6 +54,7 @@
 
 #elif defined(__HP_cc)
 # define COMPILER_ID "HP"
+  /* __HP_cc = VVRRPP */
 # define COMPILER_VERSION_MAJOR DEC(__HP_cc/10000)
 # define COMPILER_VERSION_MINOR DEC(__HP_cc/100 % 100)
 # define COMPILER_VERSION_PATCH DEC(__HP_cc     % 100)
@@ -61,6 +71,7 @@
 #  else
 #   define COMPILER_ID "VisualAge"
 #  endif
+   /* __IBMC__ = VRP */
 #  define COMPILER_VERSION_MAJOR DEC(__IBMC__/100)
 #  define COMPILER_VERSION_MINOR DEC(__IBMC__/10 % 10)
 #  define COMPILER_VERSION_PATCH DEC(__IBMC__    % 10)
@@ -96,12 +107,15 @@
 
 #elif defined(_MSC_VER)
 # define COMPILER_ID "MSVC"
+  /* _MSC_VER = VVRR */
 # define COMPILER_VERSION_MAJOR DEC(_MSC_VER / 100)
 # define COMPILER_VERSION_MINOR DEC(_MSC_VER % 100)
 # if defined(_MSC_FULL_VER)
 #  if _MSC_VER >= 1400
+    /* _MSC_FULL_VER = VVRRPPPPP */
 #   define COMPILER_VERSION_PATCH DEC(_MSC_FULL_VER % 100000)
 #  else
+    /* _MSC_FULL_VER = VVRRPPPP */
 #   define COMPILER_VERSION_PATCH DEC(_MSC_FULL_VER % 10000)
 #  endif
 # endif

Modules/CMakeCXXCompilerId.cpp.in

@@ -5,15 +5,20 @@
 # error "A C compiler has been selected for C++."
 #endif
 
+/* Version number components: V=Version, R=Revision, P=Patch
+   Version date components:   YYYY=Year, MM=Month,   DD=Day  */
+
 #if defined(__COMO__)
 # define COMPILER_ID "Comeau"
 
 #elif defined(__INTEL_COMPILER) || defined(__ICC)
 # define COMPILER_ID "Intel"
+  /* __INTEL_COMPILER = VRP */
 # define COMPILER_VERSION_MAJOR DEC(__INTEL_COMPILER/100)
 # define COMPILER_VERSION_MINOR DEC(__INTEL_COMPILER/10 % 10)
 # define COMPILER_VERSION_PATCH DEC(__INTEL_COMPILER    % 10)
 # if defined(__INTEL_COMPILER_BUILD_DATE)
+  /* __INTEL_COMPILER_BUILD_DATE = YYYYMMDD */
 #  define COMPILER_VERSION_TWEAK DEC(__INTEL_COMPILER_BUILD_DATE)
 # endif
 
@@ -25,21 +30,25 @@
 
 #elif defined(__BORLANDC__)
 # define COMPILER_ID "Borland"
+  /* __BORLANDC__ = 0xVRR */
 # define COMPILER_VERSION_MAJOR HEX(__BORLANDC__>>8)
 # define COMPILER_VERSION_MINOR HEX(__BORLANDC__ & 0xFF)
 
 #elif defined(__WATCOMC__)
 # define COMPILER_ID "Watcom"
+  /* __WATCOMC__ = VVRR */
 # define COMPILER_VERSION_MAJOR DEC(__WATCOMC__ / 100)
 # define COMPILER_VERSION_MINOR DEC(__WATCOMC__ % 100)
 
 #elif defined(__SUNPRO_CC)
 # define COMPILER_ID "SunPro"
 # if __SUNPRO_CC >= 0x5100
+   /* __SUNPRO_CC = 0xVRRP */
 #  define COMPILER_VERSION_MAJOR HEX(__SUNPRO_CC>>12)
 #  define COMPILER_VERSION_MINOR HEX(__SUNPRO_CC>>4 & 0xFF)
 #  define COMPILER_VERSION_PATCH HEX(__SUNPRO_CC    & 0xF)
 # else
+   /* __SUNPRO_CC = 0xVRP */
 #  define COMPILER_VERSION_MAJOR HEX(__SUNPRO_CC>>8)
 #  define COMPILER_VERSION_MINOR HEX(__SUNPRO_CC>>4 & 0xF)
 #  define COMPILER_VERSION_PATCH HEX(__SUNPRO_CC    & 0xF)
@@ -47,6 +56,7 @@
 
 #elif defined(__HP_aCC)
 # define COMPILER_ID "HP"
+  /* __HP_aCC = VVRRPP */
 # define COMPILER_VERSION_MAJOR DEC(__HP_aCC/10000)
 # define COMPILER_VERSION_MINOR DEC(__HP_aCC/100 % 100)
 # define COMPILER_VERSION_PATCH DEC(__HP_aCC     % 100)
@@ -63,6 +73,7 @@
 #  else
 #   define COMPILER_ID "VisualAge"
 #  endif
+   /* __IBMCPP__ = VRP */
 #  define COMPILER_VERSION_MAJOR DEC(__IBMCPP__/100)
 #  define COMPILER_VERSION_MINOR DEC(__IBMCPP__/10 % 10)
 #  define COMPILER_VERSION_PATCH DEC(__IBMCPP__    % 10)
@@ -98,12 +109,15 @@
 
 #elif defined(_MSC_VER)
 # define COMPILER_ID "MSVC"
+  /* _MSC_VER = VVRR */
 # define COMPILER_VERSION_MAJOR DEC(_MSC_VER / 100)
 # define COMPILER_VERSION_MINOR DEC(_MSC_VER % 100)
 # if defined(_MSC_FULL_VER)
 #  if _MSC_VER >= 1400
+    /* _MSC_FULL_VER = VVRRPPPPP */
 #   define COMPILER_VERSION_PATCH DEC(_MSC_FULL_VER % 100000)
 #  else
+    /* _MSC_FULL_VER = VVRRPPPP */
 #   define COMPILER_VERSION_PATCH DEC(_MSC_FULL_VER % 10000)
 #  endif
 # endif