From 27fc19e4153cefd0bb9cf44c55c87f98a430541e Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Mon, 27 Oct 2014 12:54:59 +0800
Subject: [PATCH] pyon: add doc

---
 artiq/management/pyon.py            | 28 ++++++++++++++++++++++++++++
 doc/manual/index.rst                |  1 +
 doc/manual/management_reference.rst |  8 ++++++++
 3 files changed, 37 insertions(+)
 create mode 100644 doc/manual/management_reference.rst

diff --git a/artiq/management/pyon.py b/artiq/management/pyon.py
index 25e4f22ce..70a654190 100644
--- a/artiq/management/pyon.py
+++ b/artiq/management/pyon.py
@@ -1,3 +1,23 @@
+"""
+This module provide serialization and deserialization functions for Python
+objects. Its main features are:
+
+* Human-readable format compatible with the Python syntax.
+* Each object is serialized on a single line, with only ASCII characters.
+* Supports all basic Python data structures: None, booleans, integers,
+  floats, strings, tuples, lists, dictionaries.
+* Those data types are accurately reconstructed (unlike JSON where e.g. tuples
+  become lists, and dictionary keys are turned into strings).
+* Supports Numpy arrays.
+
+The main rationale for this new custom serializer (instead of using JSON) is
+that JSON does not support Numpy and more generally cannot be extended with
+other data types while keeping a concise syntax. Here we can use the Python
+function call syntax to mark special data types.
+
+"""
+
+
 import base64
 
 import numpy
@@ -69,6 +89,10 @@ _encode_map = {
 
 
 def encode(x):
+    """Serializes a Python object and returns the corresponding string in
+    Python syntax.
+
+    """
     return _encode_map[type(x)](x)
 
 
@@ -78,4 +102,8 @@ def _nparray(shape, dtype, data):
 
 
 def decode(s):
+    """Parses a string in the Python syntax, reconstructs the corresponding
+    object, and returns it.
+
+    """
     return eval(s, {"__builtins__": None, "nparray": _nparray}, {})
diff --git a/doc/manual/index.rst b/doc/manual/index.rst
index 5dab0690e..ed3e3b301 100644
--- a/doc/manual/index.rst
+++ b/doc/manual/index.rst
@@ -10,3 +10,4 @@ Contents:
     tutorial
     core_reference
     drivers_reference
+    management_reference
diff --git a/doc/manual/management_reference.rst b/doc/manual/management_reference.rst
new file mode 100644
index 000000000..d6280aa7b
--- /dev/null
+++ b/doc/manual/management_reference.rst
@@ -0,0 +1,8 @@
+Management reference
+====================
+
+:mod:`artiq.management.pyon` module
+------------------------------------
+
+.. automodule:: artiq.management.pyon
+    :members: