python: add docstring for escaped_claim_id function

Signed-off-by: Rob van der Linde <rob@catalyst.net.nz>
Reviewed-by: Douglas Bagnall <douglas.bagnall@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>

diff --git a/python/samba/sd_utils.py b/python/samba/sd_utils.py
index 2bddfe518d2c1ecc9db1bea13fba318d362bdfeb..cabbd47b5911d5f39d0d7eb0b3ed15453a9871e8 100644 (file)
--- a/python/samba/sd_utils.py
+++ b/python/samba/sd_utils.py
@@ -29,6 +29,14 @@ from samba.ntstatus import (
 
 
 def escaped_claim_id(claim_id):
+    """Encode claim attribute names according to [MS-DTYP] 2.5.1 ("attr-char2")
+
+    Some characters must be encoded as %hhhh, while others must not be.
+    Of the optional ones, we encode some control characters.
+
+    The \x00 byte is also encoded, which is useful for tests, but it
+    is forbidden in either form.
+    """
     escapes = '\x00\t\n\x0b\x0c\r !"%&()<=>|'
     return ''.join(c
                    if c not in escapes