diff --git a/deploy/gen_messages.py b/deploy/gen_messages.py
index fa6e4484cc..b69339ee8d 100755
--- a/deploy/gen_messages.py
+++ b/deploy/gen_messages.py
@@ -278,6 +278,27 @@ class %(fac)s%(msgnam)s(%(fac)sException):%(depr)s
 \t}
 }"""
 
+# The status code is 32 bits, with these three fields:
+#    16 bit facility code in high order bits,
+#    13 bit message number, 
+#     3 bit severity (low order bits).
+#
+# The severity scheme is similar to that used by VAX VMS.
+# Every odd severity is a flavor of success ("status & 0x1" is easy check).
+# Every even severity is a flavor of error.
+#   W = warning = 0   -- bad
+#   S = success = 1   -- OK
+#   E = error = 2     -- bad
+#   I = info = 3      -- OK
+#   F = fatal = 4     -- bad
+#   ? = unused = 5    -- OK
+#   ? = unused = 6    -- bad
+#   ? = internal = 7  -- OK (see usage in mdsshr/mdsshr_messages.xml)
+#
+# SsINTERNAL is merely a synonym for -1; it is not a status code.
+# If the status variable is ever erroneously set to SsINTERNAL, note
+# that the STATUS_OK macro will treat it as success (because the low-order
+# bit is set).  See PR #2617 for details.
 
 import xml.etree.ElementTree as ET
 import sys
diff --git a/mdsshr/mdsshr_messages.xml b/mdsshr/mdsshr_messages.xml
index 08f5f93222..3bc26dc4be 100644
--- a/mdsshr/mdsshr_messages.xml
+++ b/mdsshr/mdsshr_messages.xml
@@ -50,6 +50,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   <facility name="Ss" value="0">
     <status name="SUCCESS"  value="0"  severity="Success" text="Success"/>
     <status name="INTOVF" value="143" severity="Fatal" text="Integer overflow"/>
+    <!-- SsINTERNAL is merely a synonym for -1 (i.e., 0xFFFFFFFF).  It is not a status code and should not be used with STATUS_OK, etc. -->
     <status name="INTERNAL" value="-1" severity="Internal" text="This status is meant for internal use only, you should never have seen this message."/>
   </facility>
 </messages>