doc: some precisions about controllers

sbourdeauducq · sbourdeauducq · commit 8d305e311715 · 2014-10-28T11:43:06.000+08:00
diff --git a/artiq/language/core.py b/artiq/language/core.py
@@ -84,7 +84,7 @@ def array(element, count):
 
 
 class AutoContext:
-    """Base class to automate device and parameter management.
+    """Base class to automate device and parameter discovery.
 
     Drivers and experiments should in most cases overload this class to
     obtain the parameters and devices (including the core device) that they
diff --git a/doc/manual/core_drivers_reference.rst b/doc/manual/core_drivers_reference.rst
@@ -1,8 +1,7 @@
 Core drivers reference
 ======================
 
-These drivers are for peripherals closely integrated into the core device, which do not
-follow the controller paradigm.
+These drivers are for peripherals closely integrated into the core device, which do not use the controller mechanism.
 
 :mod:`artiq.coredevice.rtio` module
 -----------------------------------
diff --git a/doc/manual/writing_a_driver.rst b/doc/manual/writing_a_driver.rst
@@ -1,7 +1,7 @@
 Writing a driver
 ================
 
-These instructions cover writing a simple driver for a "slow" device, that uses the controller paradigm.
+These instructions cover writing a simple driver for a "slow" device, that uses the controller mechanism.
 
 The controller
 --------------
@@ -52,6 +52,8 @@ and verify that you can connect to the TCP port: ::
 The client
 ----------
 
+Controller clients are small command-line utilities that expose certain functionalities of the drivers. They are optional, and not used very often - typically for debugging and testing.
+
 Create a ``hello-client`` file with the following contents: ::
 
     #!/usr/bin/env python3
@@ -74,6 +76,7 @@ Run it as before, while the controller is running. You should see the message ap
     $ ./hello-controller
     message: Hello World!
 
+When using the driver in an experiment, for simple cases the ``Client`` instance can be returned by the :class:`artiq.language.core.AutoContext` mechanism and used normally as a device.
 
 Command-line arguments
 ----------------------
