DCD doc updates

Author: orbeckst

package/MDAnalysis/coordinates/DCD.py

@@ -31,7 +31,7 @@
 :class:`DCDReader`) although there can be issues with the unitcell (simulation
 box) representation (see :attr:`DCDReader.dimensions`). DCDs can also be
 written but the :class:`DCDWriter` follows recent NAMD/VMD convention for the
-unitcell but still writes AKMA time. Reading and writing these trajectories
+unitcell while still writing AKMA time. Reading and writing these trajectories
 within MDAnalysis will work seamlessly but if you process those trajectories
 with other tools you might need to watch out that time and unitcell dimensions
 are correctly interpreted.
@@ -82,11 +82,10 @@ class DCDReader(base.ReaderBase):
     dimensions**, especially for triclinic unitcells (see `Issue 187`_). DCD
     trajectories produced by CHARMM and NAMD( >2.5) record time in AKMA units.
     If other units have been recorded (e.g., ps) then employ the configurable
-    :class:MDAnalysis.coordinates.LAMMPS.DCDReader and set the time unit as a
+    :class:`MDAnalysis.coordinates.LAMMPS.DCDReader` and set the time unit as a
     optional argument. You can find a list of units used in the DCD formats on
     the MDAnalysis `wiki`_.
 
-
     MDAnalysis always uses ``(*A*, *B*, *C*, *alpha*, *beta*, *gamma*)`` to
     represent the unit cell. Lengths *A*, *B*, *C* are in the MDAnalysis length
     unit (Å), and angles are in degrees.
@@ -96,7 +95,13 @@ class DCDReader(base.ReaderBase):
     original unitcell is read as ``[A, gamma, B, beta, alpha, C]`` from the DCD
     file. If any of these values are < 0 or if any of the angles are > 180
     degrees then it is assumed it is a new-style CHARMM unitcell (at least
-    since c36b2) in which box vectors were recorded.
+    since c36b2) in which box vectors were recorded. If all angles are numberse
+    between -1 and +1, then they are treated as cosines of the angle (following
+    the modern NAMD > 2.5/VMD convention).
+
+    Ultimately, all unitcell representations are converted to the MDAnalysis
+    standard unit cell representation in :attr:`DCDReader.dimensions`.
+
 
     .. deprecated:: 2.4.0
         DCDReader currently makes independent timesteps
@@ -118,6 +123,7 @@ class DCDReader(base.ReaderBase):
     .. _Issue 187: https://github.com/MDAnalysis/mdanalysis/issues/187
     .. _DCDplugin: http://www.ks.uiuc.edu/Research/vmd/plugins/doxygen/dcdplugin_8c-source.html#l00947
     .. _wiki: https://github.com/MDAnalysis/mdanalysis/wiki/FileFormats#dcd
+
     """
 
     format = "DCD"
@@ -375,14 +381,14 @@ class DCDWriter(base.WriterBase):
     .. warning::
 
        Multiple conventions exist for how unit cells are written to DCD
-       files. Until 2.10.0 MDAnalysis followed the old CHARMM/NAMD (≤2.5)
-       convention of storing ``[A, gamma, B, beta, alpha, C]`` while wrongly
-       stating that the new NAMD/VMD convention would be followed. In 2.10.0,
-       MDAnalysis switched to following the documented behavior and now stores
-       the box with angle cosines, as described above. The MDAnalysis
-       :class:`DCDReader` can correctly read either format but *if you have code
-       that relies on a specific format for the box information in the raw DCD
-       file, please check your results.*
+       files. Until 2.10.0 MDAnalysis followed the old X-PLOR/CHARMM/NAMD
+       (≤2.5) convention of storing ``[A, gamma, B, beta, alpha, C]`` while
+       wrongly stating that the new NAMD/VMD convention would be followed. In
+       2.10.0, MDAnalysis switched to following the documented behavior and now
+       stores the box with angle cosines, as described above. The MDAnalysis
+       :class:`DCDReader` can correctly read either format but *if you have
+       code that relies on a specific format for the box information in the raw
+       DCD file, please check your results.*
 
        Furthermore, modern versions of CHARMM store box vectors and not box
        length/angles. When reading MDAnalysis-generated DCD files *in CHARMM*,