All PDs: Improve/fix descriptions.

30 files changed, 82 insertions, 140 deletions

diff --git a/decoders/avr_isp/__init__.py b/decoders/avr_isp/__init__.py
index ff689df..4c4a900 100644
--- a/decoders/avr_isp/__init__.py
+++ b/decoders/avr_isp/__init__.py
@@ -19,14 +19,8 @@
 ##
 
 '''
-AVR ISP protocol decoder.
-
-TODO: Description.
-
-TODO: SPI is MSB-first.
-
-Details:
-TODO
+This decoder stacks on top of the 'spi' PD and decodes the In-System
+Programming (ISP) protocol of some Atmel AVR 8-bit microcontrollers.
 '''
 
 from .pd import *
diff --git a/decoders/can/__init__.py b/decoders/can/__init__.py
index fac4f6c..38731c2 100644
--- a/decoders/can/__init__.py
+++ b/decoders/can/__init__.py
@@ -19,17 +19,12 @@
 ##
 
 '''
-CAN protocol decoder.
-
-TODO: Description.
-
-Details:
-TODO
-
-Protocol output format:
-
-TODO.
+CAN (Controller Area Network) is a field bus protocol for distributed
+real-time control.
 
+This decoder assumes that a single CAN_RX line is sampled (e.g. on
+the digital output side of a CAN transceiver IC such as the Microchip
+MCP-2515DM-BM).
 '''
 
 from .pd import *
diff --git a/decoders/dcf77/__init__.py b/decoders/dcf77/__init__.py
index 71828e2..04805c2 100644
--- a/decoders/dcf77/__init__.py
+++ b/decoders/dcf77/__init__.py
@@ -19,7 +19,8 @@
 ##
 
 '''
-TODO.
+This PD decodes the DCF77 protocol (a European long-wave time signal that
+uses a 77.5kHz carrier frequency).
 
 Details:
 http://en.wikipedia.org/wiki/DCF77
diff --git a/decoders/ds1307/__init__.py b/decoders/ds1307/__init__.py
index 04db184..5bc28c3 100644
--- a/decoders/ds1307/__init__.py
+++ b/decoders/ds1307/__init__.py
@@ -19,10 +19,8 @@
 ##
 
 '''
-Dallas DS1307 RTC protocol decoder.
-
-Details:
-TODO
+This decoder stacks on top of the 'i2c' PD and decodes the Dallas DS1307
+real-time clock (RTC) specific registers and commands.
 '''
 
 from .pd import *
diff --git a/decoders/i2c/__init__.py b/decoders/i2c/__init__.py
index 95d9e18..ba40245 100644
--- a/decoders/i2c/__init__.py
+++ b/decoders/i2c/__init__.py
@@ -19,9 +19,7 @@
 ##
 
 '''
-I²C protocol decoder.
-
-The Inter-Integrated Circuit (I²C) bus is a bidirectional, multi-master
+I²C (Inter-Integrated Circuit) is a bidirectional, multi-master
 bus using two signals (SCL = serial clock line, SDA = serial data line).
 '''
 
diff --git a/decoders/i2cdemux/__init__.py b/decoders/i2cdemux/__init__.py
index 93f6c34..c5202c5 100644
--- a/decoders/i2cdemux/__init__.py
+++ b/decoders/i2cdemux/__init__.py
@@ -19,10 +19,10 @@
 ##
 
 '''
-Generic I²C demultiplexing protocol decoder.
+This is a generic I²C demultiplexing protocol decoder.
 
-Takes an I²C stream as input and outputs multiple I²C streams, each stream
-containing only I²C packets for one specific I²C slave.
+It takes an I²C stream as input and outputs multiple I²C streams, each
+stream containing only I²C packets for one specific I²C slave.
 '''
 
 from .pd import *
diff --git a/decoders/i2cfilter/__init__.py b/decoders/i2cfilter/__init__.py
index 31c3c6b..6cbab8a 100644
--- a/decoders/i2cfilter/__init__.py
+++ b/decoders/i2cfilter/__init__.py
@@ -18,9 +18,9 @@
 ##
 
 '''
-Generic I²C filtering protocol decoder.
+This is a generic I²C filtering protocol decoder.
 
-Takes input from the I²C protocol decoder and removes all traffic
+It takes input from the I²C protocol decoder and removes all traffic
 except that from/to the specified slave address and/or direction.
 
 It then outputs the filtered data again as OUTPUT_PROTO of type/format 'i2c'
diff --git a/decoders/i2s/__init__.py b/decoders/i2s/__init__.py
index e59ca96..b9c0ed7 100644
--- a/decoders/i2s/__init__.py
+++ b/decoders/i2s/__init__.py
@@ -19,9 +19,10 @@
 ##
 
 '''
-I²S protocol decoder.
+I²S (Integrated Interchip Sound) is a serial bus for connecting digital
+audio devices (usually on the same device/board).
 
-Documentation:
+Details:
 http://www.nxp.com/acrobat_download/various/I2SBUS.pdf
 http://en.wikipedia.org/wiki/I2s
 '''
diff --git a/decoders/jtag/__init__.py b/decoders/jtag/__init__.py
index 16cf6c6..047e54a 100644
--- a/decoders/jtag/__init__.py
+++ b/decoders/jtag/__init__.py
@@ -19,34 +19,10 @@
 ##
 
 '''
-JTAG protocol decoder.
-
 JTAG (Joint Test Action Group), a.k.a. "IEEE 1149.1: Standard Test Access Port
 and Boundary-Scan Architecture", is a protocol used for testing, debugging,
 and flashing various digital ICs.
 
-TODO: Protocol details.
-
-Protocol output format (WORK IN PROGRESS!):
-
-JTAG packet:
-[<packet-type>, <data>]
-
-<packet-type> is one of:
- - 'NEW STATE': <data> is the new state of the JTAG state machine.
-   Valid values: 'TEST-LOGIC-RESET', 'RUN-TEST/IDLE', 'SELECT-DR-SCAN',
-   'CAPTURE-DR', 'SHIFT-DR', 'EXIT1-DR', 'PAUSE-DR', 'EXIT2-DR', 'UPDATE-DR',
-   'SELECT-IR-SCAN', 'CAPTURE-IR', 'SHIFT-IR', 'EXIT1-IR', 'PAUSE-IR',
-   'EXIT2-IR', 'UPDATE-IR'.
- - 'IR TDI': Bitstring that was clocked into the IR register.
- - 'IR TDO': Bitstring that was clocked out of the IR register.
- - 'DR TDI': Bitstring that was clocked into the DR register.
- - 'DR TDO': Bitstring that was clocked out of the DR register.
- - ...
-
-All bitstrings are a sequence of '1' and '0' characters. The right-most
-character in the bitstring is the LSB. Example: '01110001' (1 is LSB).
-
 Details:
 https://en.wikipedia.org/wiki/Joint_Test_Action_Group
 http://focus.ti.com/lit/an/ssya002c/ssya002c.pdf
diff --git a/decoders/jtag/pd.py b/decoders/jtag/pd.py
index 55a9a1f..ea6887b 100644
--- a/decoders/jtag/pd.py
+++ b/decoders/jtag/pd.py
@@ -22,6 +22,28 @@
 
 import sigrokdecode as srd
 
+'''
+Protocol output format:
+
+JTAG packet:
+[<packet-type>, <data>]
+
+<packet-type> is one of:
+ - 'NEW STATE': <data> is the new state of the JTAG state machine.
+   Valid values: 'TEST-LOGIC-RESET', 'RUN-TEST/IDLE', 'SELECT-DR-SCAN',
+   'CAPTURE-DR', 'SHIFT-DR', 'EXIT1-DR', 'PAUSE-DR', 'EXIT2-DR', 'UPDATE-DR',
+   'SELECT-IR-SCAN', 'CAPTURE-IR', 'SHIFT-IR', 'EXIT1-IR', 'PAUSE-IR',
+   'EXIT2-IR', 'UPDATE-IR'.
+ - 'IR TDI': Bitstring that was clocked into the IR register.
+ - 'IR TDO': Bitstring that was clocked out of the IR register.
+ - 'DR TDI': Bitstring that was clocked into the DR register.
+ - 'DR TDO': Bitstring that was clocked out of the DR register.
+ - ...
+
+All bitstrings are a sequence of '1' and '0' characters. The right-most
+character in the bitstring is the LSB. Example: '01110001' (1 is LSB).
+'''
+
 jtag_states = [
         # Intro "tree"
         'TEST-LOGIC-RESET', 'RUN-TEST/IDLE',
diff --git a/decoders/jtag_stm32/__init__.py b/decoders/jtag_stm32/__init__.py
index 7618666..8a28528 100644
--- a/decoders/jtag_stm32/__init__.py
+++ b/decoders/jtag_stm32/__init__.py
@@ -19,9 +19,8 @@
 ##
 
 '''
-ST STM32 JTAG protocol decoder.
-
-TODO.
+This decoder stacks on top of the 'jtag' PD and decodes JTAG data specific to
+the STM32 microcontroller series.
 
 Details:
 https://en.wikipedia.org/wiki/STM32
diff --git a/decoders/lm75/__init__.py b/decoders/lm75/__init__.py
index 213e0ec..d096418 100644
--- a/decoders/lm75/__init__.py
+++ b/decoders/lm75/__init__.py
@@ -19,15 +19,8 @@
 ##
 
 '''
-National LM75 (and compatibles) temperature sensor protocol decoder.
-
-TODO: Description.
-
-Protocol output format:
-TODO.
-
-Details:
-TODO.
+This decoder stacks on top of the 'i2c' PD and decodes the National LM75
+(and compatibles) temperature sensor protocol.
 '''
 
 from .pd import *
diff --git a/decoders/lpc/__init__.py b/decoders/lpc/__init__.py
index e03c27e..62a4307 100644
--- a/decoders/lpc/__init__.py
+++ b/decoders/lpc/__init__.py
@@ -19,7 +19,8 @@
 ##
 
 '''
-Low-Pin Count protocol decoder.
+LPC (Low-Pin Count) is a protocol for low-bandwidth devices used on
+some PC mainboards, such as the "BIOS chip" or the so-called "Super I/O".
 '''
 
 from .pd import *
diff --git a/decoders/maxim_ds28ea00/__init__.py b/decoders/maxim_ds28ea00/__init__.py
index c5d3ca5..34d1d08 100644
--- a/decoders/maxim_ds28ea00/__init__.py
+++ b/decoders/maxim_ds28ea00/__init__.py
@@ -19,13 +19,8 @@
 ##
 
 '''
-Maxim DS28EA00 protocol decoder.
-
-The Maxim DS28EA00 is a 1-Wire digital thermometer with Sequence Detect
-and PIO functionality.
-
-Details:
-TODO
+This decoder stacks on top of the 'onewire_network' PD and decodes the
+Maxim DS28EA00 1-Wire digital thermometer protocol.
 '''
 
 from .pd import *
diff --git a/decoders/midi/__init__.py b/decoders/midi/__init__.py
index 029cfc0..a453346 100644
--- a/decoders/midi/__init__.py
+++ b/decoders/midi/__init__.py
@@ -19,11 +19,11 @@
 ##
 
 '''
-MIDI protocol decoder.
+This decoder stacks on top of the 'uart' PD and decodes the MIDI
+(Musical Instrument Digital Interface) protocol.
 
-The MIDI protocol is layered on top of the UART (async serial) protocol,
-with a fixed baud rate of 31250 baud (+/- 1%) and 8n1 settings. Bytes are
-sent LSB-first.
+MIDI is layered on top of the UART (async serial) protocol, with a fixed
+baud rate of 31250 baud (+/- 1%) and 8n1 settings. Bytes are sent LSB-first.
 '''
 
 from .pd import *
diff --git a/decoders/mlx90614/__init__.py b/decoders/mlx90614/__init__.py
index d0c6293..29cb2a9 100644
--- a/decoders/mlx90614/__init__.py
+++ b/decoders/mlx90614/__init__.py
@@ -19,10 +19,8 @@
 ##
 
 '''
-Melexis MLX90614 protocol decoder.
-
-Details:
-TODO
+This decoder stacks on top of the 'i2c' PD and decodes the Melexis MLX90614
+infrared thermometer protocol.
 '''
 
 from .pd import *
diff --git a/decoders/mx25lxx05d/__init__.py b/decoders/mx25lxx05d/__init__.py
index 047be0e..71d7b3c 100644
--- a/decoders/mx25lxx05d/__init__.py
+++ b/decoders/mx25lxx05d/__init__.py
@@ -19,11 +19,10 @@
 ##
 
 '''
-Macronix MX25Lxx05D SPI (NOR) flash chip protocol decoder.
+This decoder stacks on top of the 'spi' PD and decodes the Macronix
+MX25Lxx05D SPI (NOR) flash chip protocol.
 
-Works for MX25L1605D/MX25L3205D/MX25L6405D.
-
-TODO: Description.
+It works for the MX25L1605D/MX25L3205D/MX25L6405D.
 
 Details:
 http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/3F21BAC2E121E17848257639003A3146/$File/MX25L1605D-3205D-6405D-1.5.pdf
diff --git a/decoders/mxc6225xu/__init__.py b/decoders/mxc6225xu/__init__.py
index 783be19..c4209c8 100644
--- a/decoders/mxc6225xu/__init__.py
+++ b/decoders/mxc6225xu/__init__.py
@@ -19,15 +19,11 @@
 ##
 
 '''
-MEMSIC MXC6225XU protocol decoder.
-
-The MEMSIC MXC6225XU is a Digital Thermal Orientation Sensor (DTOS).
+This decoder stacks on top of the 'i2c' PD and decodes the MEMSIC MXC6225XU
+digital thermal orientation sensor (DTOS) protocol.
 
 The chip's I²C interface supports standard mode and fast mode (max. 400kHz).
 Its I²C slave address is 0x2a.
-
-Details:
-TODO
 '''
 
 from .pd import *
diff --git a/decoders/nunchuk/__init__.py b/decoders/nunchuk/__init__.py
index 41bc2ea..2fdaaeb 100644
--- a/decoders/nunchuk/__init__.py
+++ b/decoders/nunchuk/__init__.py
@@ -19,9 +19,8 @@
 ##
 
 '''
-Nintendo Wii Nunchuk protocol decoder.
-
-TODO: Description.
+This decoder stacks on top of the 'i2c' PD and decodes the Nintendo Wii
+Nunchuk controller protocol.
 
 Details:
 http://wiibrew.org/wiki/Wiimote/Extension_Controllers/Nunchuck
diff --git a/decoders/onewire_link/__init__.py b/decoders/onewire_link/__init__.py
index f55b998..5bd6c55 100644
--- a/decoders/onewire_link/__init__.py
+++ b/decoders/onewire_link/__init__.py
@@ -19,7 +19,7 @@
 ##
 
 '''
-1-Wire protocol decoder (link layer).
+This protocol decoder handles the 1-Wire link layer.
 
 The 1-Wire protocol enables bidirectional communication over a single wire
 (and ground) between a single master and one or multiple slaves. The protocol
@@ -29,8 +29,6 @@ is layered:
  - Network layer (skip/search/match device ROM addresses)
  - Transport layer (transport data between 1-Wire master and device)
 
-This protocol decoder handles the 1-Wire link layer.
-
 Sample rate:
 A sufficiently high samplerate is required to properly detect all the elements
 of the protocol. A lower samplerate can be used if the master does not use
diff --git a/decoders/onewire_network/__init__.py b/decoders/onewire_network/__init__.py
index f184a3d..31e9134 100644
--- a/decoders/onewire_network/__init__.py
+++ b/decoders/onewire_network/__init__.py
@@ -19,7 +19,8 @@
 ##
 
 '''
-1-Wire protocol decoder (network layer).
+This decoder stacks on top of the 'onewire_link' PD and decodes the
+1-Wire protocol (network layer).
 
 The 1-Wire protocol enables bidirectional communication over a single wire
 (and ground) between a single master and one or multiple slaves. The protocol
@@ -31,11 +32,6 @@ is layered:
 
 Network layer:
 
-Protocol output format:
-TODO.
-
-Annotations:
-
 The following link layer annotations are shown:
 
  - RESET/PRESENCE True/False
diff --git a/decoders/pan1321/__init__.py b/decoders/pan1321/__init__.py
index 02e2da5..9bda523 100644
--- a/decoders/pan1321/__init__.py
+++ b/decoders/pan1321/__init__.py
@@ -19,10 +19,8 @@
 ##
 
 '''
-Panasonic PAN1321 protocol decoder.
-
-Details:
-TODO
+This decoder stacks on top of the 'uart' PD and decodes the Panasonic PAN1321
+Bluetooth module Serial Port Profile (SPP) protocol.
 '''
 
 from .pd import *
diff --git a/decoders/rtc8564/__init__.py b/decoders/rtc8564/__init__.py
index 6e67fe9..9a397b1 100644
--- a/decoders/rtc8564/__init__.py
+++ b/decoders/rtc8564/__init__.py
@@ -19,10 +19,8 @@
 ##
 
 '''
-Epson RTC-8564 JE/NB protocol decoder.
-
-Details:
-TODO
+This decoder stacks on top of the 'i2c' PD and decodes the Epson
+RTC-8564 JE/NB real-time clock (RTC) protocol.
 '''
 
 from .pd import *
diff --git a/decoders/sdcard_spi/__init__.py b/decoders/sdcard_spi/__init__.py
index 18f9c9a..293b654 100644
--- a/decoders/sdcard_spi/__init__.py
+++ b/decoders/sdcard_spi/__init__.py
@@ -19,9 +19,8 @@
 ##
 
 '''
-SD card (SPI mode) low-level protocol decoder.
-
-TODO: Description.
+This decoder stacks on top of the 'spi' PD and decodes the SD card
+(SPI mode) low-level protocol.
 
 Most SD cards can be accessed via two different protocols/modes: SD mode
 or SPI mode.
@@ -65,9 +64,6 @@ SPI mode properties (differences to SD mode):
  * In SPI mode cards cannot guarantee their speed class (the host should
    assume class 0, no matter what the card indicates).
  * The RCA register is not accessible in SPI mode.
-
-Details:
-TODO
 '''
 
 from .pd import *
diff --git a/decoders/spi/__init__.py b/decoders/spi/__init__.py
index 582891a..a65f167 100644
--- a/decoders/spi/__init__.py
+++ b/decoders/spi/__init__.py
@@ -19,11 +19,9 @@
 ##
 
 '''
-Serial Peripheral Interface protocol decoder.
-
-This protocol decoder supports synchronous SPI(-like) protocols with a
-clock line, a MISO and MOSI line for data transfer in two directions,
-and an optional CS# pin.
+The SPI (Serial Peripheral Interface) protocol decoder supports synchronous
+SPI(-like) protocols with a clock line, a MISO and MOSI line for data
+transfer in two directions, and an optional CS# pin.
 
 If CS# is supplied, data is only decoded when CS# is asserted (clock
 transitions where CS# is not asserted are ignored). If CS# is not supplied,
diff --git a/decoders/tlc5620/__init__.py b/decoders/tlc5620/__init__.py
index 6cf3401..c615760 100644
--- a/decoders/tlc5620/__init__.py
+++ b/decoders/tlc5620/__init__.py
@@ -19,7 +19,7 @@
 ##
 
 '''
-Texas Instruments TLC5620 protocol decoder.
+The Texas Instruments TLC5620 is an 8-bit quad DAC.
 '''
 
 from .pd import *
diff --git a/decoders/uart/__init__.py b/decoders/uart/__init__.py
index a0c9cef..f3c0693 100644
--- a/decoders/uart/__init__.py
+++ b/decoders/uart/__init__.py
@@ -19,13 +19,11 @@
 ##
 
 '''
-UART protocol decoder.
-
-Universal Asynchronous Receiver Transmitter (UART) is a simple serial
+UART (Universal Asynchronous Receiver Transmitter) is a simple serial
 communication protocol which allows two devices to talk to each other.
 
 This decoder should work on all "UART-like" async protocols with one
-start bit (0), 7-9 databits, an (optional) parity bit, and one or more
+start bit (0), 5-9 databits, an (optional) parity bit, and one or more
 stop bits (1), in this order.
 
 It can be run on one signal line (RX or TX) only, or on two lines (RX + TX).
diff --git a/decoders/usb_packet/__init__.py b/decoders/usb_packet/__init__.py
index 555dc7f..06b67b9 100644
--- a/decoders/usb_packet/__init__.py
+++ b/decoders/usb_packet/__init__.py
@@ -19,7 +19,8 @@
 ##
 
 '''
-USB (low-speed and full-speed) packet protocol decoder.
+This decoder stacks on top of the 'usb_signalling' PD and decodes the USB
+(low-speed and full-speed) packet protocol.
 
 Protocol layer (USB spec, chapter 8):
 
@@ -35,9 +36,6 @@ PID: A PID (packet identifier) follows the SYNC field of every packet. A PID
 consists of a 4-bit packet type field, and a 4 bit check field.
 The check field is the one's complement of the packet type field.
 
-Protocol output format:
-TODO
-
 Details:
 https://en.wikipedia.org/wiki/USB
 http://www.usb.org/developers/docs/
diff --git a/decoders/usb_signalling/__init__.py b/decoders/usb_signalling/__init__.py
index 32902e4..2311b1f 100644
--- a/decoders/usb_signalling/__init__.py
+++ b/decoders/usb_signalling/__init__.py
@@ -19,7 +19,7 @@
 ##
 
 '''
-USB (low-speed and full-speed) signalling protocol decoder.
+This PD decodes the USB (low-speed and full-speed) signalling protocol.
 
 Electrical/signalling layer (USB spec, chapter 7):
 
@@ -43,9 +43,6 @@ Data is transferred at a rate of 1.5Mbit/s (low-speed) / 12Mbit/s (full-speed).
 The SE0 transmitted to signal an end-of-packet is two bit intervals long
 (low-speed: 1.25uS - 1.50uS, full-speed: 160ns - 175ns).
 
-Protocol output format:
-TODO
-
 Details:
 https://en.wikipedia.org/wiki/USB
 http://www.usb.org/developers/docs/
diff --git a/decoders/xfp/__init__.py b/decoders/xfp/__init__.py
index 627f07b..fa4e8a2 100644
--- a/decoders/xfp/__init__.py
+++ b/decoders/xfp/__init__.py
@@ -19,7 +19,7 @@
 ##
 
 '''
-XFP I²C management interface structure decoder.
+This PD decodes the XFP I²C management interface structures/protocol.
 
 XFP modules include an I²C interface, used to monitor and control various
 aspects of the module. The specification defines an I²C slave at address