From 6e9e0a60eb17bab313521cf12f12895ac2ec8678 Mon Sep 17 00:00:00 2001
From: Robert Jordens <jordens@gmail.com>
Date: Thu, 28 Nov 2013 01:46:52 -0700
Subject: [PATCH] setup API documentation, start by documenting fifos

---
 doc/api.rst          |  8 +++++++
 doc/index.rst        |  1 +
 migen/genlib/fifo.py | 50 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 doc/api.rst

diff --git a/doc/api.rst b/doc/api.rst
new file mode 100644
index 000000000..06f233054
--- /dev/null
+++ b/doc/api.rst
@@ -0,0 +1,8 @@
+migen Package
+=============
+
+:mod:`genlib.fifo` Module
+------------------------------
+
+.. automodule:: migen.genlib.fifo
+        :members:
diff --git a/doc/index.rst b/doc/index.rst
index 6f3644dcb..6c21d762f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -10,3 +10,4 @@ Migen manual
    dataflow
    simulation
    casestudies
+   api
diff --git a/migen/genlib/fifo.py b/migen/genlib/fifo.py
index afb397f83..0e4ce54ef 100644
--- a/migen/genlib/fifo.py
+++ b/migen/genlib/fifo.py
@@ -13,6 +13,37 @@ def _inc(signal, modulo):
 		)
 
 class _FIFOInterface:
+	"""
+	Data written to the input interface (`din`, `we`, `writable`) is
+	buffered and can be read at the output interface (`dout`, `re`,
+	`readable`). The data entry written first to the input 
+	also appears first on the output.
+
+	Parameters
+	==========
+	width_or_layout : int, layout
+		Bit width or `Record` layout for the data.
+	depth : int
+		Depth of the FIFO.
+
+	Attributes
+	==========
+	din : in, width_or_layout
+		Input data either flat or Record structured.
+	writable : out
+		There is space in the FIFO and `we` can be asserted.
+	we : in
+		Write enable signal to latch `din` into the FIFO. Only assert if
+		`writable` is asserted.
+	dout : out, width_or_layout
+		Output data, same type as `din`. Only valid if `readable` is
+		asserted.
+	readable : out
+		Output data `dout` valid, FIFO not empty.
+	re : in
+		Acknowledge `dout`. If asserted, the next entry will be
+		available on the next cycle (if `readable` is high then).
+	"""
 	def __init__(self, width_or_layout, depth):
 		self.we = Signal()
 		self.writable = Signal() # not full
@@ -33,6 +64,15 @@ class _FIFOInterface:
 			self.width = width_or_layout
 
 class SyncFIFO(Module, _FIFOInterface):
+	"""Synchronous FIFO (first in, first out)
+
+	Read and write interfaces are accessed from the same clock domain.
+	If different clock domains are needed, use :class:`AsyncFIFO`.
+
+	{interface}
+	"""
+	__doc__ = __doc__.format(interface=_FIFOInterface.__doc__)
+
 	def __init__(self, width_or_layout, depth):
 		_FIFOInterface.__init__(self, width_or_layout, depth)
 
@@ -81,6 +121,16 @@ class SyncFIFO(Module, _FIFOInterface):
 		]
 
 class AsyncFIFO(Module, _FIFOInterface):
+	"""Asynchronous FIFO (first in, first out)
+
+	Read and write interfaces are accessed from different clock domains,
+	named `read` and `write`. Use `RenameClockDomains` to rename to
+	other names.
+
+	{interface}
+	"""
+	__doc__ = __doc__.format(interface=_FIFOInterface.__doc__)
+
 	def __init__(self, width_or_layout, depth):
 		_FIFOInterface.__init__(self, width_or_layout, depth)