From: Uwe Hermann <redacted>
Date: Wed, 1 Feb 2012 21:23:03 +0000 (+0100)
Subject: srd: Move all protocol docs to __init__.py files.
X-Git-Tag: libsigrokdecode-0.1.0~67
X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=commitdiff_plain;h=156509ca42f0df2380c9f205f9aad337e1a07802

srd: Move all protocol docs to __init__.py files.
---

diff --git a/decoders/dcf77/__init__.py b/decoders/dcf77/__init__.py
index db7d2de..bef505b 100644
--- a/decoders/dcf77/__init__.py
+++ b/decoders/dcf77/__init__.py
@@ -18,5 +18,12 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+TODO.
+
+Details:
+http://en.wikipedia.org/wiki/DCF77
+'''
+
 from .dcf77 import *
 
diff --git a/decoders/dcf77/dcf77.py b/decoders/dcf77/dcf77.py
index 098c3b9..ab600ed 100644
--- a/decoders/dcf77/dcf77.py
+++ b/decoders/dcf77/dcf77.py
@@ -18,17 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # DCF77 protocol decoder
-#
-# More information:
-# http://en.wikipedia.org/wiki/DCF77
-#
-
-#
-# Protocol output format:
-# TODO
-#
 
 import sigrokdecode as srd
 import calendar
diff --git a/decoders/ebr30a_i2c_demux/__init__.py b/decoders/ebr30a_i2c_demux/__init__.py
index dddc8b7..a5df143 100644
--- a/decoders/ebr30a_i2c_demux/__init__.py
+++ b/decoders/ebr30a_i2c_demux/__init__.py
@@ -18,5 +18,19 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+TrekStor EBR30-a I2C demux protocol decoder.
+
+Takes an I2C stream as input and outputs 3 different I2C streams, for the
+3 different I2C devices on the TrekStor EBR30-a eBook reader (which are all
+physically connected to the same SCL/SDA lines).
+
+I2C slave addresses:
+
+ - AXP199 battery management chip: 0x69/0x68 (8bit R/W), 0x34 (7bit)
+ - H8563S RTC chip: 0xa3/0xa2 (8bit R/W), 0x51 (7bit)
+ - Unknown accelerometer chip: 0x2b/0x2a (8bit R/W), 0x15 (7bit)
+'''
+
 from .ebr30a_i2c_demux import *
 
diff --git a/decoders/ebr30a_i2c_demux/ebr30a_i2c_demux.py b/decoders/ebr30a_i2c_demux/ebr30a_i2c_demux.py
index 6abed09..1a52fb8 100644
--- a/decoders/ebr30a_i2c_demux/ebr30a_i2c_demux.py
+++ b/decoders/ebr30a_i2c_demux/ebr30a_i2c_demux.py
@@ -18,19 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # TrekStor EBR30-a I2C demux protocol decoder
-#
-# Takes an I2C stream as input and outputs 3 different I2C streams, for the
-# 3 different I2C devices on the TrekStor EBR30-a eBook reader (which are all
-# physically connected to the same SCL/SDA lines).
-#
-# I2C slave addresses:
-#
-#  - AXP199 battery management chip: 0x69/0x68 (8bit R/W), 0x34 (7bit)
-#  - H8563S RTC chip: 0xa3/0xa2 (8bit R/W), 0x51 (7bit)
-#  - Unknown accelerometer chip: 0x2b/0x2a (8bit R/W), 0x15 (7bit)
-#
 
 import sigrokdecode as srd
 
diff --git a/decoders/edid/edid.py b/decoders/edid/edid.py
index 6d53bf1..78ea4f6 100644
--- a/decoders/edid/edid.py
+++ b/decoders/edid/edid.py
@@ -17,6 +17,8 @@
 ## along with this program; if not, see <http://www.gnu.org/licenses/>.
 ##
 
+# EDID protocol decoder
+
 # TODO:
 #    - EDID < 1.3
 #    - add short annotations
diff --git a/decoders/i2c/__init__.py b/decoders/i2c/__init__.py
index 9e7856e..3c29aa1 100644
--- a/decoders/i2c/__init__.py
+++ b/decoders/i2c/__init__.py
@@ -18,5 +18,63 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+I2C protocol decoder.
+
+The Inter-Integrated Circuit (I2C) bus is a bidirectional, multi-master
+bus using two signals (SCL = serial clock line, SDA = serial data line).
+
+There can be many devices on the same bus. Each device can potentially be
+master or slave (and that can change during runtime). Both slave and master
+can potentially play the transmitter or receiver role (this can also
+change at runtime).
+
+Possible maximum data rates:
+ - Standard mode: 100 kbit/s
+ - Fast mode: 400 kbit/s
+ - Fast-mode Plus: 1 Mbit/s
+ - High-speed mode: 3.4 Mbit/s
+
+START condition (S): SDA = falling, SCL = high
+Repeated START condition (Sr): same as S
+Data bit sampling: SCL = rising
+STOP condition (P): SDA = rising, SCL = high
+
+All data bytes on SDA are exactly 8 bits long (transmitted MSB-first).
+Each byte has to be followed by a 9th ACK/NACK bit. If that bit is low,
+that indicates an ACK, if it's high that indicates a NACK.
+
+After the first START condition, a master sends the device address of the
+slave it wants to talk to. Slave addresses are 7 bits long (MSB-first).
+After those 7 bits, a data direction bit is sent. If the bit is low that
+indicates a WRITE operation, if it's high that indicates a READ operation.
+
+Later an optional 10bit slave addressing scheme was added.
+
+Documentation:
+http://www.nxp.com/acrobat/literature/9398/39340011.pdf (v2.1 spec)
+http://www.nxp.com/acrobat/usermanuals/UM10204_3.pdf (v3 spec)
+http://en.wikipedia.org/wiki/I2C
+
+Protocol output format:
+
+I2C packet:
+[<i2c_command>, <data>, <ack_bit>]
+
+<i2c_command> is one of:
+  - 'START' (START condition)
+  - 'START REPEAT' (Repeated START)
+  - 'ADDRESS READ' (Address, read)
+  - 'ADDRESS WRITE' (Address, write)
+  - 'DATA READ' (Data, read)
+  - 'DATA WRITE' (Data, write)
+  - 'STOP' (STOP condition)
+
+<data> is the data or address byte associated with the 'ADDRESS*' and 'DATA*'
+command. For 'START', 'START REPEAT' and 'STOP', this is None.
+
+<ack_bit> is either 'ACK' or 'NACK', but may also be None.
+'''
+
 from .i2c import *
 
diff --git a/decoders/i2c/i2c.py b/decoders/i2c/i2c.py
index 527fa6e..b1c4a8a 100644
--- a/decoders/i2c/i2c.py
+++ b/decoders/i2c/i2c.py
@@ -18,46 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # I2C protocol decoder
-#
-
-#
-# The Inter-Integrated Circuit (I2C) bus is a bidirectional, multi-master
-# bus using two signals (SCL = serial clock line, SDA = serial data line).
-#
-# There can be many devices on the same bus. Each device can potentially be
-# master or slave (and that can change during runtime). Both slave and master
-# can potentially play the transmitter or receiver role (this can also
-# change at runtime).
-#
-# Possible maximum data rates:
-#  - Standard mode: 100 kbit/s
-#  - Fast mode: 400 kbit/s
-#  - Fast-mode Plus: 1 Mbit/s
-#  - High-speed mode: 3.4 Mbit/s
-#
-# START condition (S): SDA = falling, SCL = high
-# Repeated START condition (Sr): same as S
-# Data bit sampling: SCL = rising
-# STOP condition (P): SDA = rising, SCL = high
-#
-# All data bytes on SDA are exactly 8 bits long (transmitted MSB-first).
-# Each byte has to be followed by a 9th ACK/NACK bit. If that bit is low,
-# that indicates an ACK, if it's high that indicates a NACK.
-#
-# After the first START condition, a master sends the device address of the
-# slave it wants to talk to. Slave addresses are 7 bits long (MSB-first).
-# After those 7 bits, a data direction bit is sent. If the bit is low that
-# indicates a WRITE operation, if it's high that indicates a READ operation.
-#
-# Later an optional 10bit slave addressing scheme was added.
-#
-# Documentation:
-# http://www.nxp.com/acrobat/literature/9398/39340011.pdf (v2.1 spec)
-# http://www.nxp.com/acrobat/usermanuals/UM10204_3.pdf (v3 spec)
-# http://en.wikipedia.org/wiki/I2C
-#
 
 # TODO: Look into arbitration, collision detection, clock synchronisation, etc.
 # TODO: Handle clock stretching.
@@ -69,27 +30,6 @@
 # TODO: Handle multiple different I2C devices on same bus
 #       -> we need to decode multiple protocols at the same time.
 
-'''
-Protocol output format:
-
-I2C packet:
-[<i2c_command>, <data>, <ack_bit>]
-
-<i2c_command> is one of:
-  - 'START' (START condition)
-  - 'START REPEAT' (Repeated START)
-  - 'ADDRESS READ' (Address, read)
-  - 'ADDRESS WRITE' (Address, write)
-  - 'DATA READ' (Data, read)
-  - 'DATA WRITE' (Data, write)
-  - 'STOP' (STOP condition)
-
-<data> is the data or address byte associated with the 'ADDRESS*' and 'DATA*'
-command. For 'START', 'START REPEAT' and 'STOP', this is None.
-
-<ack_bit> is either 'ACK' or 'NACK', but may also be None.
-'''
-
 import sigrokdecode as srd
 
 # Annotation feed formats
diff --git a/decoders/i2cdemux/__init__.py b/decoders/i2cdemux/__init__.py
index 83f7b12..445a88e 100644
--- a/decoders/i2cdemux/__init__.py
+++ b/decoders/i2cdemux/__init__.py
@@ -18,5 +18,12 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+Generic I2C demultiplexing protocol decoder.
+
+Takes an I2C stream as input and outputs multiple I2C streams, each stream
+containing only I2C packets for one specific I2C slave.
+'''
+
 from .i2cdemux import *
 
diff --git a/decoders/i2cdemux/i2cdemux.py b/decoders/i2cdemux/i2cdemux.py
index 354d06c..a597188 100644
--- a/decoders/i2cdemux/i2cdemux.py
+++ b/decoders/i2cdemux/i2cdemux.py
@@ -18,12 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # Generic I2C demultiplexing protocol decoder
-#
-# Takes an I2C stream as input and outputs multiple I2C streams, each stream
-# containing only I2C packets for one specific I2C slave.
-#
 
 import sigrokdecode as srd
 
diff --git a/decoders/i2cfilter/__init__.py b/decoders/i2cfilter/__init__.py
index 6c5f1ec..e9a9ab6 100644
--- a/decoders/i2cfilter/__init__.py
+++ b/decoders/i2cfilter/__init__.py
@@ -18,6 +18,8 @@
 ##
 
 '''
+Generic I2C filtering protocol decoder.
+
 Takes input from the I2C protocol decoder and filters out traffic from/to
 a single address on the I2C bus.
 
diff --git a/decoders/i2cfilter/i2cfilter.py b/decoders/i2cfilter/i2cfilter.py
index 4b88bef..da816e6 100644
--- a/decoders/i2cfilter/i2cfilter.py
+++ b/decoders/i2cfilter/i2cfilter.py
@@ -17,8 +17,9 @@
 ## along with this program; if not, see <http://www.gnu.org/licenses/>.
 ##
 
-import sigrokdecode as srd
+# Generic I2C filtering protocol decoder
 
+import sigrokdecode as srd
 
 class Decoder(srd.Decoder):
     api_version = 1
diff --git a/decoders/mlx90614/mlx90614.py b/decoders/mlx90614/mlx90614.py
index 4cc39a3..f50e568 100644
--- a/decoders/mlx90614/mlx90614.py
+++ b/decoders/mlx90614/mlx90614.py
@@ -18,9 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # Melexis MLX90614 Infrared Thermometer protocol decoder
-#
 
 import sigrokdecode as srd
 
diff --git a/decoders/mx25lxx05d/__init__.py b/decoders/mx25lxx05d/__init__.py
index 0affc99..26b1a58 100644
--- a/decoders/mx25lxx05d/__init__.py
+++ b/decoders/mx25lxx05d/__init__.py
@@ -18,5 +18,16 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+Macronix MX25Lxx05D SPI (NOR) flash chip decoder.
+
+Works for MX25L1605D/MX25L3205D/MX25L6405D.
+
+TODO: Description.
+
+Details:
+http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/3F21BAC2E121E17848257639003A3146/$File/MX25L1605D-3205D-6405D-1.5.pdf
+'''
+
 from .mx25lxx05d import *
 
diff --git a/decoders/mx25lxx05d/mx25lxx05d.py b/decoders/mx25lxx05d/mx25lxx05d.py
index a21ba3f..801ab80 100644
--- a/decoders/mx25lxx05d/mx25lxx05d.py
+++ b/decoders/mx25lxx05d/mx25lxx05d.py
@@ -18,17 +18,9 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
-# Macronix MX25Lxx05D SPI (NOR) flash chip decoder.
-# Works for MX25L1605D/MX25L3205D/MX25L6405D.
-#
+# Macronix MX25Lxx05D SPI (NOR) flash chip protocol decoder
 
-#
-# TODO: Description
-#
-# Details:
-# http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/3F21BAC2E121E17848257639003A3146/$File/MX25L1605D-3205D-6405D-1.5.pdf
-#
+# Note: Works for MX25L1605D/MX25L3205D/MX25L6405D.
 
 import sigrokdecode as srd
 
diff --git a/decoders/nunchuk/__init__.py b/decoders/nunchuk/__init__.py
index 6772ba7..da6db06 100644
--- a/decoders/nunchuk/__init__.py
+++ b/decoders/nunchuk/__init__.py
@@ -18,5 +18,16 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+Nintendo Wii Nunchuk decoder.
+
+TODO: Description.
+
+Details:
+http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck
+http://todbot.com/blog/2008/02/18/wiichuck-wii-nunchuck-adapter-available/
+https://www.sparkfun.com/products/9281
+'''
+
 from .nunchuk import *
 
diff --git a/decoders/nunchuk/nunchuk.py b/decoders/nunchuk/nunchuk.py
index db40d35..f901905 100644
--- a/decoders/nunchuk/nunchuk.py
+++ b/decoders/nunchuk/nunchuk.py
@@ -18,17 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
-# Nintendo Wii Nunchuk decoder
-#
-
-#
-# TODO: Description
-#
-# http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck
-# http://todbot.com/blog/2008/02/18/wiichuck-wii-nunchuck-adapter-available/
-# https://www.sparkfun.com/products/9281
-#
+# Nintendo Wii Nunchuk protocol decoder
 
 import sigrokdecode as srd
 
diff --git a/decoders/pan1321/pan1321.py b/decoders/pan1321/pan1321.py
index e89b6a0..2c7e6c6 100644
--- a/decoders/pan1321/pan1321.py
+++ b/decoders/pan1321/pan1321.py
@@ -18,11 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # Panasonic PAN1321 Bluetooth module protocol decoder
-#
-# TODO
-#
 
 import sigrokdecode as srd
 
diff --git a/decoders/rtc8564/rtc8564.py b/decoders/rtc8564/rtc8564.py
index 18f8c24..00bfb27 100644
--- a/decoders/rtc8564/rtc8564.py
+++ b/decoders/rtc8564/rtc8564.py
@@ -18,9 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
-# Epson RTC-8564 JE/NB decoder
-#
+# Epson RTC-8564 JE/NB protocol decoder
 
 import sigrokdecode as srd
 
diff --git a/decoders/spi/spi.py b/decoders/spi/spi.py
index bbf0f37..dfe83b9 100644
--- a/decoders/spi/spi.py
+++ b/decoders/spi/spi.py
@@ -19,6 +19,8 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+# SPI protocol decoder
+
 import sigrokdecode as srd
 
 # Key: (CPOL, CPHA). Value: SPI mode.
diff --git a/decoders/transitioncounter/transitioncounter.py b/decoders/transitioncounter/transitioncounter.py
index 4156bfc..4b458b2 100644
--- a/decoders/transitioncounter/transitioncounter.py
+++ b/decoders/transitioncounter/transitioncounter.py
@@ -18,6 +18,8 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+# Transition counter protocol decoder
+
 import sigrokdecode as srd
 
 class Decoder(srd.Decoder):
diff --git a/decoders/uart/__init__.py b/decoders/uart/__init__.py
index 1c7f317..43e7706 100644
--- a/decoders/uart/__init__.py
+++ b/decoders/uart/__init__.py
@@ -19,6 +19,8 @@
 ##
 
 '''
+UART protocol decoder.
+
 Universal Asynchronous Receiver Transmitter (UART) is a simple serial
 communication protocol which allows two devices to talk to each other.
 
diff --git a/decoders/uart/uart.py b/decoders/uart/uart.py
index 1604834..dd9f88d 100644
--- a/decoders/uart/uart.py
+++ b/decoders/uart/uart.py
@@ -18,9 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
 # UART protocol decoder
-#
 
 import sigrokdecode as srd
 
diff --git a/decoders/usb/__init__.py b/decoders/usb/__init__.py
index 068cadf..77b58d1 100644
--- a/decoders/usb/__init__.py
+++ b/decoders/usb/__init__.py
@@ -18,5 +18,27 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
+'''
+USB (full-speed) protocol decoder.
+
+Full-speed USB signalling consists of two signal lines, both driven at 3.3V
+logic levels. The signals are DP (D+) and DM (D-), and normally operate in
+differential mode.
+The state where DP=1,DM=0 is J, the state DP=0,DM=1 is K.
+A state SE0 is defined where DP=DM=0. This common mode signal is used to
+signal a reset or end of packet.
+
+Data transmitted on the USB is encoded with NRZI. A transition from J to K
+or vice-versa indicates a logic 0, while no transition indicates a logic 1.
+If 6 ones are transmitted consecutively, a zero is inserted to force a
+transition. This is known as bit stuffing. Data is transferred at a rate
+of 12Mbit/s. The SE0 transmitted to signal an end-of-packet is two bit
+intervals long.
+
+Details:
+https://en.wikipedia.org/wiki/USB
+http://www.usb.org/developers/docs/
+'''
+
 from .usb import *
 
diff --git a/decoders/usb/usb.py b/decoders/usb/usb.py
index b209aa3..99dd4b5 100644
--- a/decoders/usb/usb.py
+++ b/decoders/usb/usb.py
@@ -18,27 +18,7 @@
 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
 ##
 
-#
-# USB Full-speed protocol decoder
-#
-# Full-speed USB signalling consists of two signal lines, both driven at 3.3V
-# logic levels. The signals are DP (D+) and DM (D-), and normally operate in
-# differential mode.
-# The state where DP=1,DM=0 is J, the state DP=0,DM=1 is K.
-# A state SE0 is defined where DP=DM=0. This common mode signal is used to
-# signal a reset or end of packet.
-#
-# Data transmitted on the USB is encoded with NRZI. A transition from J to K
-# or vice-versa indicates a logic 0, while no transition indicates a logic 1.
-# If 6 ones are transmitted consecutively, a zero is inserted to force a
-# transition. This is known as bit stuffing. Data is transferred at a rate
-# of 12Mbit/s. The SE0 transmitted to signal an end-of-packet is two bit
-# intervals long.
-#
-# Details:
-# https://en.wikipedia.org/wiki/USB
-# http://www.usb.org/developers/docs/
-#
+# USB (full-speed) protocol decoder
 
 import sigrokdecode as srd