Build: Document SO_AGE and TURBOJPEG_SO_AGE vars

CMakeLists.txt

@@ -287,6 +287,16 @@ if(NOT WITH_JPEG8)
   report_option(WITH_MEM_SRCDST "In-memory source/destination managers")
 endif()
 
+# 0: Original libjpeg v6b/v7/v8 API/ABI
+#
+# libjpeg v6b/v7 API/ABI emulation:
+# 1: + In-memory source/destination managers (libjpeg-turbo 1.3.x)
+# 2: + Partial image decompression functions (libjpeg-turbo 1.5.x)
+# 3: + ICC functions (libjpeg-turbo 2.0.x)
+#
+# libjpeg v8 API/ABI emulation:
+# 1: + Partial image decompression functions (libjpeg-turbo 1.5.x)
+# 2: + ICC functions (libjpeg-turbo 2.0.x)
 set(SO_AGE 2)
 if(WITH_MEM_SRCDST)
   set(SO_AGE 3)
@@ -337,8 +347,19 @@ message(STATUS "libjpeg API shared library version = ${SO_MAJOR_VERSION}.${SO_AG
 # names of functions whenever they are modified in a backward-incompatible
 # manner, it is always backward-ABI-compatible with itself, so the major and
 # minor SO versions don't change.  However, we increase the middle number (the
-# SO "age") whenever functions are added to the API.
+# SO "age") whenever functions are added to the API, because adding functions
+# affects forward API/ABI compatibility.
 set(TURBOJPEG_SO_MAJOR_VERSION 0)
+# 0: TurboJPEG 1.3.x API
+# 1: TurboJPEG 1.4.x API
+#    The TurboJPEG 1.5.x API modified some of the function prototypes, adding
+#    the const keyword in front of pointers to unmodified buffers, but that did
+#    not affect forward API/ABI compatibility.
+# 2: TurboJPEG 2.0.x API
+#    The TurboJPEG 2.1.x API modified the behavior of the tjDecompressHeader3()
+#    function so that it accepts "abbreviated table specification" (AKA
+#    "tables-only") datastreams as well as JPEG images, but that did not affect
+#    forward API/ABI compatibility.
 set(TURBOJPEG_SO_AGE 2)
 set(TURBOJPEG_SO_VERSION 0.${TURBOJPEG_SO_AGE}.0)