-#
-# I2C input format:
-#
-# signals:
-# [[id, channel, description], ...] # TODO
-#
-# Example:
-# {'id': 'SCL', 'ch': 5, 'desc': 'Serial clock line'}
-# {'id': 'SDA', 'ch': 7, 'desc': 'Serial data line'}
-# ...
-#
-# {'inbuf': [...],
-# 'signals': [{'SCL': }]}
-#
+"""
+I2C protocol output format:
+
+The protocol output consists of a (Python) list of I2C "packets", each of
+which is of the form
+
+ [ _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.