From 5b26fb10a9551e72d57c7d1894d067b19f55b00e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <jordens@gmail.com>
Date: Fri, 29 Nov 2013 02:36:48 -0700
Subject: [PATCH] genlib/coding: add docstrings, add it to api doc

---
 doc/api.rst            |  7 +++++
 migen/genlib/coding.py | 62 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index c9f8427b3..1362caa98 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -14,3 +14,10 @@ migen API Documentation
 .. automodule:: migen.genlib.fifo
         :members:
         :show-inheritance:
+
+:mod:`genlib.coding` Module
+------------------------------
+
+.. automodule:: migen.genlib.coding
+        :members:
+        :show-inheritance:
diff --git a/migen/genlib/coding.py b/migen/genlib/coding.py
index 94a224ea2..ed0315576 100644
--- a/migen/genlib/coding.py
+++ b/migen/genlib/coding.py
@@ -2,13 +2,28 @@ from migen.fhdl.std import *
 
 """
 Encoders and decoders between binary and one-hot representation
-
-i: input (binary or one-hot)
-o: output (one-hot or binary)
-n: "none" signal (in/out), binary value is invalid
 """
 
 class Encoder(Module):
+	"""Encode one-hot to binary
+
+	If `n` is low, the `o` th bit in `i` is asserted, else none or
+	multiple bits are asserted.
+
+	Parameters
+	----------
+	width : int
+		Bit width of the input
+
+	Attributes
+	----------
+	i : Signal(width), in
+		One-hot input
+	o : Signal(max=width), out
+		Encoded binary
+	n : Signal(1), out
+		Invalid, either none or multiple input bits are asserted
+	"""
 	def __init__(self, width):
 		self.i = Signal(width) # one-hot
 		self.o = Signal(max=width) # binary
@@ -18,6 +33,25 @@ class Encoder(Module):
 		self.comb += Case(self.i, act)
 
 class PriorityEncoder(Module):
+	"""Priority encode requests to binary
+
+	If `n` is low, the `o` th bit in `i` is asserted and the bits below
+	`o` are unasserted, else `o == 0`. The LSB has priority.
+
+	Parameters
+	----------
+	width : int
+		Bit width of the input
+
+	Attributes
+	----------
+	i : Signal(width), in
+		Input requests
+	o : Signal(max=width), out
+		Encoded binary
+	n : Signal(1), out
+		Invalid, no input bits are asserted
+	"""
 	def __init__(self, width):
 		self.i = Signal(width) # one-hot, lsb has priority
 		self.o = Signal(max=width) # binary
@@ -27,6 +61,26 @@ class PriorityEncoder(Module):
 		self.comb += self.n.eq(self.i == 0)
 
 class Decoder(Module):
+	"""Decode binary to one-hot
+
+	If `n` is low, the `i` th bit in `o` is asserted, the others are
+	not, else `o == 0`.
+
+	Parameters
+	----------
+	width : int
+		Bit width of the output
+
+	Attributes
+	----------
+	i : Signal(max=width), in
+		Input binary
+	o : Signal(width), out
+		Decoded one-hot
+	n : Signal(1), in
+		Invalid, no output bits are to be asserted
+	"""
+
 	def __init__(self, width):
 		self.i = Signal(max=width) # binary
 		self.n = Signal() # none/invalid