diff --git a/base_classes/NXdisk_chopper.nxdl.xml b/base_classes/NXdisk_chopper.nxdl.xml
index a1afadf673..c5e61e7025 100644
--- a/base_classes/NXdisk_chopper.nxdl.xml
+++ b/base_classes/NXdisk_chopper.nxdl.xml
@@ -2,9 +2,9 @@
 <?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
 <!--
 # NeXus - Neutron and X-ray Common Data Format
-# 
+#
 # Copyright (C) 2008-2018 NeXus International Advisory Committee (NIAC)
-# 
+#
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
 # License as published by the Free Software Foundation; either
@@ -24,13 +24,28 @@
 <definition xmlns="http://definition.nexusformat.org/nxdl/3.1" category="base"
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
-	name="NXdisk_chopper" 
+	name="NXdisk_chopper"
 	type="group" extends="NXobject">
-	
+
+	<symbols>
+		<doc>This symbol will be used below to coordinate datasets with the same shape.</doc>
+		<symbol name="n"><doc>Number of slits in the disk</doc></symbol>
+	</symbols>
+
 	<doc>
 		A device blocking the beam in a temporal periodic pattern.
-		
-		TODO: need documentation
+
+		A disk which blocks the beam but has one or more slits to periodically
+		let neutrons through as the disk rotates. Often used in pairs, one
+		NXdisk_chopper should be defined for each disk.
+
+		The rotation of the disk is commonly monitored by recording a timestamp for
+		each full rotation of disk, by having a sensor in the stationary disk housing
+		sensing when it is aligned with a feature (such as a magnet) on the disk.
+		We refer to this below as the "top-dead-center signal".
+
+		Angles and positive rotation speeds are measured in an anticlockwise
+		direction when facing away from the source.
 	</doc>
 
 	<field name="type">
@@ -42,37 +57,69 @@
 		</enumeration>
 	</field>
 	<field name="rotation_speed" type="NX_FLOAT" units="NX_FREQUENCY">
-		<doc>chopper rotation speed</doc>
+		<doc>
+			Chopper rotation speed. Positive for anticlockwise rotation when
+			facing away from the source, negative otherwise.
+		</doc>
 	</field>
 	<field name="slits" type="NX_INT">
 		<doc>Number of slits</doc>
 	</field>
 	<field name="slit_angle" type="NX_FLOAT" units="NX_ANGLE">
-		<doc>angular opening</doc>
+		<doc>Angular opening</doc>
 	</field>
 	<field name="pair_separation" type="NX_FLOAT" units="NX_LENGTH">
-		<doc>disc spacing in direction of beam</doc>
+		<doc>Disk spacing in direction of beam</doc>
+	</field>
+	<field name="slit_edges" type="NX_FLOAT" units="NX_ANGLE">
+		<doc>
+			Angle of the each edge of each slit from the position of the
+			top-dead-center timestamp sensor, anticlockwise when facing the sample.
+			The first edge must be the opening edge of a slit, thus the last edge
+			may have an angle greater than 360 degrees.
+		</doc>
+		<dimensions><dim index="1" value="2n"/></dimensions>
+	</field>
+	<field name="top_dead_center" type="NX_NUMBER" units="NX_TIME">
+		<doc>
+			Timestamps of the top-dead-center signal. The times are relative
+			to the "start" attribute and in the units specified in the "units"
+			attribute. Please note that absolute
+			timestamps under unix are relative to ``1970-01-01T:00:00``.
+		</doc>
+		<attribute name="start" type="NX_DATE_TIME" />
+	</field>
+	<field name="beam_position" type="NX_FLOAT" units="NX_ANGLE">
+		<doc>
+			Angular separation of the center of the beam and the
+			top-dead-center timestamp sensor, anticlockwise when facing the sample.
+		</doc>
 	</field>
 	<field name="radius" type="NX_FLOAT" units="NX_LENGTH">
-		<doc>radius to centre of slit</doc>
+		<doc>Radius of the disk</doc>
 	</field>
 	<field name="slit_height" type="NX_FLOAT" units="NX_LENGTH">
-		<doc>total slit height</doc>
+		<doc>Total slit height</doc>
 	</field>
 	<field name="phase" type="NX_FLOAT" units="NX_ANGLE">
-		<doc>chopper phase angle</doc>
+		<doc>Chopper phase angle</doc>
+	</field>
+	<field name="delay" type="NX_NUMBER" units="NX_TIME">
+		<doc>
+			Time difference between timing system t0 and chopper driving clock signal
+		</doc>
 	</field>
 	<field name="ratio" type="NX_INT">
-	  <doc>
-            pulse reduction factor of this chopper in relation to other
-            choppers/fastest pulse in the instrument
-	  </doc>
+		<doc>
+			Pulse reduction factor of this chopper in relation to other
+			choppers/fastest pulse in the instrument
+		</doc>
 	</field>
 	<field name="distance" type="NX_FLOAT" units="NX_LENGTH">
 		<doc>Effective distance to the origin</doc>
 	</field>
 	<field name="wavelength_range" type="NX_FLOAT" units="NX_WAVELENGTH">
-		<doc>low and high values of wavelength range transmitted</doc>
+		<doc>Low and high values of wavelength range transmitted</doc>
 		<dimensions><dim index="1" value="2"/></dimensions>
 	</field>
 	<group type="NXgeometry" />