DOC: Add the spec text to explain the dim discrepancy

Author: effigies

nibabel/cifti2/cifti2.py

@@ -1476,6 +1476,16 @@ def to_file_map(self, file_map=None):
     def update_headers(self):
         ''' Harmonize NIfTI headers with image data
 
+        Ensures that the NIfTI-2 header records the data shape in the last three
+        ``dim`` fields. Per the spec:
+
+            Because the first four dimensions in NIfTI are reserved for space and time, the CIFTI
+            dimensions are stored in the NIfTI header in dim[5] and up, where dim[5] is the length
+            of the first CIFTI dimension (number of values in a row), dim[6] is the length of the
+            second CIFTI dimension, and dim[7] is the length of the third CIFTI dimension, if
+            applicable. The fields dim[1] through dim[4] will be 1; dim[0] will be 6 or 7,
+            depending on whether a third matrix dimension exists.
+
         >>> import numpy as np
         >>> data = np.zeros((2,3,4))
         >>> img = Cifti2Image(data)