diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml
index f926e479ff..c147df2c57 100644
--- a/applications/NXmx.nxdl.xml
+++ b/applications/NXmx.nxdl.xml
@@ -375,7 +375,9 @@
 
 					<field name="pixel_mask" type="NX_INT" minOccurs="0">
 						<doc>
-							The 32-bit pixel mask for the detector.
+							The 32-bit pixel mask for the detector. Can be either one mask
+							for the whole dataset (rank i, j, k) or each frame can have its own
+							mask (rank np, i, j, k).
 							Contains a bit field
 							for each pixel to signal dead,
 							blind or high or otherwise unwanted
diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml
index cb680c0125..70346f002e 100644
--- a/base_classes/NXdetector.nxdl.xml
+++ b/base_classes/NXdetector.nxdl.xml
@@ -587,7 +587,10 @@
   </field>
   <field name="pixel_mask" type="NX_INT" >
     <doc>
-      The 32-bit pixel mask for the detector.
+      The 32-bit pixel mask for the detector. Can be either one mask
+      for the whole dataset (rank i, j) or each frame can have its own
+      mask (rank np, i, j).
+
       Contains a bit field for each pixel to signal dead,
       blind or high or otherwise unwanted or undesirable pixels.
       They have the following meaning:
@@ -606,11 +609,19 @@
       * bits 9-30: -undefined-
       * bit 31: virtual pixel (corner pixel with interpolated value)
 
-      The normal data analysis software would not take pixels into
-      account when a bit in (mask &amp; 0x00FF) is set.
-      Tag bit in the upper two bytes would indicate special pixel
-      properties that normally would not be a sole reason to
-      reject the intensity value (unless lower bits are also set).
+      Normal data analysis software would
+      not take pixels into account
+      when a bit in (mask &amp; 0x0000FFFF) is
+      set. Tag bit in the upper
+      two bytes would indicate special pixel
+      properties that normally
+      would not be a sole reason to reject the
+      intensity value (unless
+      lower bits are set.
+
+      If the full bit depths is not required, providing a
+      mask with fewer bits is permissible.
+
     </doc>
     <dimensions rank="2">
       <dim index="1" value="i"/>