Merge pull request #538 from sheilatron/Docstrings4Learning

Improve docstring for NameID and argtree.add_path

Author: c00kiemon5ter

src/saml2/argtree.py

@@ -53,10 +53,34 @@ def set_arg(cls, arg, value):
 
 def add_path(tdict, path):
     """
+    Create or extend an argument tree `tdict` from `path`.
 
     :param tdict: a dictionary representing a argument tree
     :param path: a path list
     :return: a dictionary
+
+    Convert a list of items in a 'path' into a nested dict, where the
+    second to last item becomes the key for the final item. The remaining
+    items in the path become keys in the nested dict around that final pair
+    of items.
+
+    For example, for input values of:
+        tdict={}
+        path = ['assertion', 'subject', 'subject_confirmation',
+                'method', 'urn:oasis:names:tc:SAML:2.0:cm:bearer']
+
+        Returns an output value of:
+           {'assertion': {'subject': {'subject_confirmation':
+                         {'method': 'urn:oasis:names:tc:SAML:2.0:cm:bearer'}}}}
+
+    Another example, this time with a non-empty tdict input:
+
+        tdict={'method': 'urn:oasis:names:tc:SAML:2.0:cm:bearer'},
+        path=['subject_confirmation_data', 'in_response_to', '_012345']
+
+        Returns an output value of:
+            {'subject_confirmation_data': {'in_response_to': '_012345'},
+             'method': 'urn:oasis:names:tc:SAML:2.0:cm:bearer'}
     """
     t = tdict
     for step in path[:-2]:

src/saml2/saml.py

@@ -811,7 +811,16 @@ def base_id_from_string(xml_string):
 
 
 class NameID(NameIDType_):
-    """The urn:oasis:names:tc:SAML:2.0:assertion:NameID element """
+    """The urn:oasis:names:tc:SAML:2.0:assertion:NameID element
+
+    From the Oasis SAML2 Technical Overview:
+
+    "The <NameID> element within a <Subject> offers the ability to provide name
+     identifiers in a number of different formats. SAML's predefined formats
+     include: Email address, X.509 subject name, Windows domain qualified name,
+     Kerberos principal name, Entity identifier, Persistent identifier,
+     Transient identifier."
+     """
 
     c_tag = 'NameID'
     c_namespace = NAMESPACE