From cb036a30c7650de75564fe96adfdbc2f8b37b0d5 Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Tue, 30 Sep 2014 17:38:52 +0800
Subject: [PATCH] devices/dds_core: document

---
 artiq/devices/dds_core.py        | 29 +++++++++++++++++++++++++++++
 doc/manual/drivers_reference.rst |  6 ++++++
 2 files changed, 35 insertions(+)

diff --git a/artiq/devices/dds_core.py b/artiq/devices/dds_core.py
index e842f38a8..0b61cf128 100644
--- a/artiq/devices/dds_core.py
+++ b/artiq/devices/dds_core.py
@@ -4,6 +4,20 @@ from artiq.devices import rtio_core
 
 
 class DDS(AutoContext):
+    """Core device Direct Digital Synthesis (DDS) driver.
+
+    This driver controls DDS devices managed directly by the core device's
+    runtime. It also uses a RTIO channel (through
+    :class:`artiq.devices.rtio_core.RTIOOut`) to control a RF switch that
+    gates the output of the DDS device.
+
+    :param dds_sysclk: DDS system frequency, used for computing the frequency
+        tuning words.
+    :param reg_channel: channel number of the DDS device to control.
+    :param rtio_channel: RTIO channel number of the RF switch associated with
+        the DDS device.
+
+    """
     parameters = "dds_sysclk reg_channel rtio_channel"
 
     def build(self):
@@ -14,6 +28,12 @@ class DDS(AutoContext):
 
     @kernel
     def on(self, frequency):
+        """Sets the DDS channel to the specified frequency and turns it on.
+
+        If the DDS channel was already on, a real-time frequency update is
+        performed.
+
+        """
         if self.previous_frequency != frequency:
             if self.sw.previous_timestamp != now():
                 self.sw.sync()
@@ -35,10 +55,19 @@ class DDS(AutoContext):
 
     @kernel
     def off(self):
+        """Turns the DDS channel off.
+
+        """
         self.sw.off()
 
     @kernel
     def pulse(self, frequency, duration):
+        """Pulses the DDS channel for the specified duration at the specified
+        frequency.
+
+        Equivalent to a ``on``, ``delay``, ``off`` sequence.
+
+        """
         self.on(frequency)
         delay(duration)
         self.off()
diff --git a/doc/manual/drivers_reference.rst b/doc/manual/drivers_reference.rst
index cf133913f..60378625f 100644
--- a/doc/manual/drivers_reference.rst
+++ b/doc/manual/drivers_reference.rst
@@ -6,3 +6,9 @@ Drivers reference
 
 .. automodule:: artiq.devices.rtio_core
     :members:
+
+:mod:`artiq.devices.dds_core` module
+-------------------------------------
+
+.. automodule:: artiq.devices.dds_core
+    :members: