doc: add doc comments
diff --git a/serial/tools/hexlify_codec.py b/serial/tools/hexlify_codec.py
index 6d42080..f8449e2 100644
--- a/serial/tools/hexlify_codec.py
+++ b/serial/tools/hexlify_codec.py
@@ -3,11 +3,19 @@
# This is a codec to create and decode hexdumps with spaces between characters. used by miniterm.
#
# This file is part of pySerial. https://github.com/pyserial/pyserial
-# (C) 2011 Chris Liechti <cliechti@gmx.net>
+# (C) 2015-2016 Chris Liechti <cliechti@gmx.net>
#
# SPDX-License-Identifier: BSD-3-Clause
"""\
Python 'hex' Codec - 2-digit hex with spaces content transfer encoding.
+
+Encode and decode may be a bit missleading at first sight...
+
+The textual representation is a hex dump: e.g. "40 41"
+The "encoded" data of this is the binary form, e.g. b"@A"
+
+Therefore decoding is binary to text and thus converting binary data to hex dump.
+
"""
import codecs
@@ -18,23 +26,28 @@
# Codec APIs
-def hex_encode(input, errors='strict'):
- return (serial.to_bytes([int(h, 16) for h in input.split()]), len(input))
+def hex_encode(data, errors='strict'):
+ """'40 41 42' -> '@ab'"""
+ return (serial.to_bytes([int(h, 16) for h in data.split()]), len(data))
-def hex_decode(input, errors='strict'):
- return (''.join('{:02X} '.format(b) for b in input), len(input))
+def hex_decode(data, errors='strict'):
+ """'@ab' -> '40 41 42'"""
+ return (''.join('{:02X} '.format(b) for b in data), len(data))
class Codec(codecs.Codec):
- def encode(self, input, errors='strict'):
- return serial.to_bytes([int(h, 16) for h in input.split()])
+ def encode(self, data, errors='strict'):
+ """'40 41 42' -> '@ab'"""
+ return serial.to_bytes([int(h, 16) for h in data.split()])
- def decode(self, input, errors='strict'):
- return ''.join('{:02X} '.format(b) for b in input)
+ def decode(self, data, errors='strict'):
+ """'@ab' -> '40 41 42'"""
+ return ''.join('{:02X} '.format(b) for b in data)
class IncrementalEncoder(codecs.IncrementalEncoder):
+ """Incremental hex encoder"""
def __init__(self, errors='strict'):
self.errors = errors
@@ -49,10 +62,15 @@
def setstate(self, state):
self.state = state
- def encode(self, input, final=False):
+ def encode(self, data, final=False):
+ """\
+ Incremental encode, keep track of digits and emit a byte when a pair
+ of hex digits is found. The space is optional unless the error
+ handling is defined to be 'strict'.
+ """
state = self.state
encoded = []
- for c in input.upper():
+ for c in data.upper():
if c in HEXDIGITS:
z = HEXDIGITS.index(c)
if state:
@@ -72,21 +90,21 @@
class IncrementalDecoder(codecs.IncrementalDecoder):
- def decode(self, input, final=False):
- return ''.join('{:02X} '.format(b) for b in input)
+ """Incremental decoder"""
+ def decode(self, data, final=False):
+ return ''.join('{:02X} '.format(b) for b in data)
class StreamWriter(Codec, codecs.StreamWriter):
- pass
+ """Combination of hexlify codec and StreamWriter"""
class StreamReader(Codec, codecs.StreamReader):
- pass
+ """Combination of hexlify codec and StreamReader"""
-# encodings module API
-
def getregentry():
+ """encodings module API"""
return codecs.CodecInfo(
name='hexlify',
encode=hex_encode,