xattr-helper: add docstrings to more places

diff --git a/bin/xattr-helper.py b/bin/xattr-helper.py
index 6d33017670b85200d96d422d7295c77bcc0d4b5b..92bf1a28a198b5bd5be8f92a909902a891ab2b4d 100755 (executable)
--- a/bin/xattr-helper.py
+++ b/bin/xattr-helper.py
@@ -2,6 +2,15 @@
 # Copyright 2012-2013 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 
+"""Dump and restore extended attributes.
+
+We use formats like that used by getfattr --dump.  This is meant for shell
+helpers to save/restore.  If you're looking for a python/portage API, see
+portage.util.movefile._copyxattr instead.
+
+https://en.wikipedia.org/wiki/Extended_file_attributes
+"""
+
 import array
 import os
 import re
@@ -43,8 +52,12 @@ else:
                        s = s.encode(_FS_ENCODING)
                return s
 
+
 def quote(s, quote_chars):
+       """Convert all |quote_chars| in |s| to escape sequences
 
+       This is normally used to escape any embedded quotation marks.
+       """
        quote_re = re.compile(b'[' + quote_chars + b']')
        result = []
        pos = 0
@@ -63,8 +76,9 @@ def quote(s, quote_chars):
 
        return b"".join(result)
 
-def unquote(s):
 
+def unquote(s):
+       """Process all escape sequences in |s|"""
        result = []
        pos = 0
        s_len = len(s)
@@ -88,7 +102,9 @@ def unquote(s):
 
        return b"".join(result)
 
+
 def dump_xattrs(file_in, file_out):
+       """Dump the xattr data for files in |file_in| to |file_out|"""
 
        for pathname in file_in.read().split(b'\0'):
                if not pathname:
@@ -107,7 +123,10 @@ def dump_xattrs(file_in, file_out):
                                quote(xattr.get(pathname, attr), b'\0\n\r"\\\\') + b'"\n')
 
 def restore_xattrs(file_in):
+       """Read |file_in| and restore xattrs content from it
 
+       This expects textual data in the format written by dump_xattrs.
+       """
        pathname = None
        for i, line in enumerate(file_in):
                if line.startswith(b'# file: '):
@@ -173,6 +192,7 @@ def main(argv):
 
        return os.EX_OK
 
+
 if __name__ == "__main__":
        rval = main(sys.argv[:])
        sys.exit(rval)