libcli-acl: add documentation

Reviewed-by: Andrew Bartlett <abartlet@samba.org>
(cherry picked from commit b1e231384a9245a191ef5e004544d7cafe17e036)

The last 44 patches address bug #8909 - ACL problem with delegation of
privileges and deletion of accounts over LDAP interface.

diff --git a/libcli/security/access_check.c b/libcli/security/access_check.c
index f0a7b665c75dd37e15da9cebf639d4a1a2aaa9c7..936ffca242e6b6e7682f97dc3815e54715ee8fe9 100644 (file)
--- a/libcli/security/access_check.c
+++ b/libcli/security/access_check.c
@@ -374,7 +374,25 @@ static const struct GUID *get_ace_object_type(struct security_ace *ace)
        return NULL;
 }
 
-/* modified access check for the purposes of DS security
+/**
+ * @brief Perform directoryservice (DS) related access checks for a given user
+ *
+ * Perform DS access checks for the user represented by its security_token, on
+ * the provided security descriptor. If an tree associating GUID and access
+ * required is provided then object access (OA) are checked as well. *
+ * @param[in]   sd             The security descritor against which the required
+ *                             access are requested
+ *
+ * @param[in]   token          The security_token associated with the user to
+ *                             test
+ *
+ * @param[in]   access_desired A bitfield of rights that must be granted for the
+ *                             given user in the specified SD.
+ *
+ * If one
+ * of the entry in the tree grants all the requested rights for the given GUID
+ * FIXME
+ * tree can be null if not null it's the
  * Lots of code duplication, it will ve united in just one
  * function eventually */