type_decoder: update and extend Decoder base class doc strings

[libsigrokdecode.git] / decoders / parallel / __init__.py

diff --git a/decoders/parallel/__init__.py b/decoders/parallel/__init__.py
index ea55077d04804d51d5979212b8ccfafebc1c3d88..e7ed36cb2c7d452331f05fdd20c20ff2068818b6 100644 (file)
--- a/decoders/parallel/__init__.py
+++ b/decoders/parallel/__init__.py
@@ -14,23 +14,32 @@
 ## GNU General Public License for more details.
 ##
 ## You should have received a copy of the GNU General Public License
-## along with this program; if not, write to the Free Software
-## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+## along with this program; if not, see <http://www.gnu.org/licenses/>.
 ##
 
 '''
 This protocol decoder can decode synchronous parallel buses with various
-number of data bits/probes and one (optional) clock line.
+data bits/channels counts, an (optional) clock line, and an (optional)
+select/enable/reset line.
 
-If no clock line is supplied, the decoder works slightly differently in
-that it interprets every transition on any of the supplied data probes
-like there had been a clock transition.
+Data bits are taken from the decoder's lowest connected input pins. The
+input signal's data lines count need not span the full amount of the
+decoder's maximum supported data lines count. Not connected data lines
+are assumed to be low.
 
-It is required to use the lowest data probes, and use consecutive ones.
-For example, for a 4-bit sync parallel bus, probes D0/D1/D2/D3 (and CLK)
-should be used. Using combinations like D7/D12/D3/D15 is not supported.
-For an 8-bit bus you should use D0-D7, for a 16-bit bus use D0-D15 and so on.
-'''
+Example use cases are: Connect D3/D2/D1/D0 (and CLK) to a 4-bit bus.
+Connect D7 and D6 to inspect the two most significant bits of an 8-bit
+bus (and have 8-bit values shown instead of just 2-bit values).
+
+When provided, the specified clock edge determines when data lines get
+sampled. Without a clock spec, each transition on any of the data lines
+will be shown, which can become busy/noisy depending on the input data.
 
-from .pd import *
+Another signal optionally can control the period of time within which
+the data lines' bit pattern gets interpreted. Typical use cases would be
+reset, or select, or enable signals that are related to the bus' data
+communication. This optional signal can also improve synchronization to
+wider payload data which spans several bus cycles (multiplexing).
+'''
 
+from .pd import Decoder