From ac5dd0a7e5a1a79684cf1dcb443f8bbf81b1fb96 Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Fri, 21 Aug 2015 13:32:53 +0800
Subject: [PATCH] doc: scans

---
 artiq/language/scan.py                 | 38 ++++++++++++++++++++++++++
 doc/manual/core_language_reference.rst |  6 ++++
 2 files changed, 44 insertions(+)

diff --git a/artiq/language/scan.py b/artiq/language/scan.py
index 90867737d..a65ce566c 100644
--- a/artiq/language/scan.py
+++ b/artiq/language/scan.py
@@ -1,3 +1,23 @@
+"""
+Implementation and management of scan objects.
+
+A scan object (e.g. :class:`artiq.language.scan.LinearScan`) represents a
+one-dimensional sweep of a numerical range. Multi-dimensional scans are
+constructed by combining several scan objects.
+
+Iterate on a scan object to scan it, e.g. ::
+
+    for variable in self.scan:
+        do_something(variable)
+
+Iterating multiple times on the same scan object is possible, with the scan
+restarting at the minimum value each time. Iterating concurrently on the
+same scan object (e.g. via nested loops) is also supported, and the
+iterators are independent from each other.
+
+Scan objects are supported both on the host and the core device.
+"""
+
 from random import Random, shuffle
 import inspect
 
@@ -9,6 +29,7 @@ __all__ = ["NoScan", "LinearScan", "RandomScan", "ExplicitScan", "Scannable"]
 
 
 class NoScan:
+    """A scan object that yields a single value."""
     def __init__(self, value):
         self.value = value
 
@@ -25,6 +46,8 @@ class NoScan:
 
 
 class LinearScan:
+    """A scan object that yields a fixed number of increasing evenly
+    spaced values in a range."""
     def __init__(self, min, max, npoints):
         self.min = min
         self.max = max
@@ -47,6 +70,8 @@ class LinearScan:
 
 
 class RandomScan:
+    """A scan object that yields a fixed number of randomly ordered evenly
+    spaced values in a range."""
     def __init__(self, min, max, npoints, seed=0):
         self.sequence = list(LinearScan(min, max, npoints))
         shuffle(self.sequence, Random(seed).random)
@@ -61,6 +86,7 @@ class RandomScan:
 
 
 class ExplicitScan:
+    """A scan object that yields values from a explicitly defined sequence."""
     def __init__(self, sequence):
         self.sequence = sequence
 
@@ -81,6 +107,18 @@ _ty_to_scan = {
 
 
 class Scannable:
+    """An argument (as defined in :class:`artiq.language.environment`) that
+    takes a scan object.
+
+    :param global_min: The minimum value taken by the scanned variable, common
+        to all scan modes. The user interface takes this value to set the
+        range of its input widgets.
+    :param global_max: Same as global_min, but for the maximum value.
+    :param global_step: The step with which the value should be modified by
+        up/down buttons in a user interface.
+    :param unit: A string representing the unit of the scanned variable, for user
+        interface purposes.
+    """
     def __init__(self, global_min=None, global_max=None, global_step=None,
                  unit="", default=NoDefault):
         self.global_min = global_min
diff --git a/doc/manual/core_language_reference.rst b/doc/manual/core_language_reference.rst
index f4efa4335..b88b95ade 100644
--- a/doc/manual/core_language_reference.rst
+++ b/doc/manual/core_language_reference.rst
@@ -15,6 +15,12 @@ The most commonly used features from those modules can be imported with ``from a
 .. automodule:: artiq.language.environment
     :members:
 
+:mod:`artiq.language.scan` module
+----------------------------------------
+
+.. automodule:: artiq.language.scan
+    :members:
+
 :mod:`artiq.language.units` module
 ----------------------------------