Improved docs as per review suggestions

gssapi/raw/ext_ggf.pyx

@@ -1,3 +1,16 @@
+"""
+GGF Extensions
+
+GGF provides extended credential and security context inquiry that allows
+application to retrieve more information about the client's credentials and
+security context. One common use case is to use gss_inquire_sec_context_by_oid
+to retrieve the "session" key that is required by the SMB protocol for signing
+and encrypting a message. These calls are provided as a part of the raw
+interface and are not exposed in the high-level interface.
+
+Draft IETF document for these extensions can be found at
+https://tools.ietf.org/html/draft-engert-ggf-gss-extensions-00
+"""
 GSSAPI="BASE"  # This ensures that a full module is generated by Cython
 
 from gssapi.raw.cython_types cimport *
@@ -21,20 +34,21 @@ cdef extern from "python_gssapi_ext.h":
                                              gss_buffer_set_t *data_set) nogil
 
 
-def inquire_cred_by_oid(Creds cred_handle not None, OID mech not None):
+def inquire_cred_by_oid(Creds cred_handle not None,
+                        OID desired_aspect not None):
     """
-    inquire_cred_by_oid(cred_handle, mech)
+    inquire_cred_by_oid(cred_handle, desired_aspect)
 
     This method inspects a :class:`Creds` object for information
-    specific to a particular mechanism.
+    specific to a particular desired aspect as an OID.
 
     Args:
-        cred_handle (Creds): the security context to query
-        mech (OID): the desired mechanism
+        cred_handle (Creds): the Credentials to query
+        desired_aspect (OID): the desired aspect of the Credentials to inquire
+            about.
 
     Returns:
-        list: A list of zero or more pieces of data corresponding to the
-            OID set
+        list: A list of zero or more pieces of data (as bytes objects)
 
     Raises:
         GSS_ERROR
@@ -48,7 +62,7 @@ def inquire_cred_by_oid(Creds cred_handle not None, OID mech not None):
 
     with nogil:
         maj_stat = gss_inquire_cred_by_oid(&min_stat, cred_handle.raw_creds,
-                                           &mech.raw_oid, data_set_ptr)
+                                           &desired_aspect.raw_oid, data_set_ptr)
 
     if maj_stat == GSS_S_COMPLETE:
         py_tokens = []
@@ -66,24 +80,24 @@ def inquire_cred_by_oid(Creds cred_handle not None, OID mech not None):
 
 
 def inquire_sec_context_by_oid(SecurityContext context not None,
-                               OID mech not None):
+                               OID desired_aspect not None):
     """
-    inquire_sec_context_by_oid(context, mech)
+    inquire_sec_context_by_oid(context, desired_aspect)
 
     This method inspects a :class:`SecurityContext` object for information
-    specific to a particular mechanism.
+    specific to a particular desired aspect as an OID.
 
     This method can be used with the GSS_KRB5_INQ_SSPI_SESSION_KEY_OID OID to
     retrieve the required key that is used to derive the SMB/SAMBA signing and
     encryption keys.
 
     Args:
-        context (SecurityContext): the security context to query
-        mech (OID): the desired mechanism
+        context (SecurityContext): the Security Context to query
+        desired_aspect (OID): the desired aspected of the Security Context to
+            inquire about.
 
     Returns:
-        list: A list of zero or more pieces of data corresponding to the
-            OID set
+        list: A list of zero or more pieces of data (as bytes objects)
 
     Raises:
         GSS_ERROR
@@ -97,7 +111,8 @@ def inquire_sec_context_by_oid(SecurityContext context not None,
 
     with nogil:
         maj_stat = gss_inquire_sec_context_by_oid(&min_stat, context.raw_ctx,
-                                                  &mech.raw_oid, data_set_ptr)
+                                                  &desired_aspect.raw_oid,
+                                                  data_set_ptr)
 
     if maj_stat == GSS_S_COMPLETE:
         py_tokens = []