Move the doxygen comments of wbclient to the header file.
authorAndreas Schneider <anschneider@suse.de>
Tue, 9 Dec 2008 12:18:06 +0000 (13:18 +0100)
committerMichael Adam <obnox@samba.org>
Wed, 10 Dec 2008 22:23:36 +0000 (23:23 +0100)
So that a developer who wants to use the wbclient api can read
the documentation in the header file.

Signed-off-by: Andreas Schneider <anschneider@suse.de>
Signed-off-by: Michael Adam <obnox@samba.org>
source3/nsswitch/libwbclient/wbc_guid.c
source3/nsswitch/libwbclient/wbc_idmap.c
source3/nsswitch/libwbclient/wbc_pam.c
source3/nsswitch/libwbclient/wbc_pwd.c
source3/nsswitch/libwbclient/wbc_sid.c
source3/nsswitch/libwbclient/wbc_util.c
source3/nsswitch/libwbclient/wbclient.c
source3/nsswitch/libwbclient/wbclient.h

index 0cb33e9..c343e24 100644 (file)
 
 #include "libwbclient.h"
 
-/** @brief Convert a binary GUID to a character string
- *
- * @param guid           Binary Guid
- * @param **guid_string  Resulting character string
- *
- * @return #wbcErr
- **/
-
+/* Convert a binary GUID to a character string */
 wbcErr wbcGuidToString(const struct wbcGuid *guid,
                       char **guid_string)
 {
@@ -59,14 +52,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Convert a character string to a binary GUID
- *
- * @param *str          Character string
- * @param guid          Resulting binary GUID
- *
- * @return #wbcErr
- **/
-
+/* @brief Convert a character string to a binary GUID */
 wbcErr wbcStringToGuid(const char *str,
                       struct wbcGuid *guid)
 {
index 81b369c..5b2ab87 100644 (file)
 
 #include "libwbclient.h"
 
-/** @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
- *
- * @param *sid        Pointer to the domain SID to be resolved
- * @param *puid       Pointer to the resolved uid_t value
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a Windows SID to a Unix uid, allocating an uid if needed */
 wbcErr wbcSidToUid(const struct wbcDomainSid *sid, uid_t *puid)
 {
        struct winbindd_request request;
@@ -71,30 +63,14 @@ wbcErr wbcSidToUid(const struct wbcDomainSid *sid, uid_t *puid)
        return wbc_status;
 }
 
-/** @brief Convert a Windows SID to a Unix uid if there already is a mapping
- *
- * @param *sid        Pointer to the domain SID to be resolved
- * @param *puid       Pointer to the resolved uid_t value
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a Windows SID to a Unix uid if there already is a mapping */
 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
                        uid_t *puid)
 {
        return WBC_ERR_NOT_IMPLEMENTED;
 }
 
-/** @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
- *
- * @param uid         Unix uid to be resolved
- * @param *sid        Pointer to the resolved domain SID
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a Unix uid to a Windows SID, allocating a SID if needed */
 wbcErr wbcUidToSid(uid_t uid, struct wbcDomainSid *sid)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -127,15 +103,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Convert a Unix uid to a Windows SID if there already is a mapping
- *
- * @param uid         Unix uid to be resolved
- * @param *sid        Pointer to the resolved domain SID
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a Unix uid to a Windows SID if there already is a mapping */
 wbcErr wbcQueryUidToSid(uid_t uid,
                        struct wbcDomainSid *sid)
 {
@@ -189,14 +157,7 @@ wbcErr wbcSidToGid(const struct wbcDomainSid *sid, gid_t *pgid)
        return wbc_status;
 }
 
-/** @brief Convert a Windows SID to a Unix gid if there already is a mapping
- *
- * @param *sid        Pointer to the domain SID to be resolved
- * @param *pgid       Pointer to the resolved gid_t value
- *
- * @return #wbcErr
- *
- **/
+/* Convert a Windows SID to a Unix gid if there already is a mapping */
 
 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
                        gid_t *pgid)
@@ -204,15 +165,7 @@ wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
        return WBC_ERR_NOT_IMPLEMENTED;
 }
 
-/** @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
- *
- * @param gid         Unix gid to be resolved
- * @param *sid        Pointer to the resolved domain SID
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a Unix gid to a Windows SID, allocating a SID if needed */
 wbcErr wbcGidToSid(gid_t gid, struct wbcDomainSid *sid)
 {
        struct winbindd_request request;
@@ -245,28 +198,14 @@ done:
        return wbc_status;
 }
 
-/** @brief Convert a Unix gid to a Windows SID if there already is a mapping
- *
- * @param gid         Unix gid to be resolved
- * @param *sid        Pointer to the resolved domain SID
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a Unix gid to a Windows SID if there already is a mapping */
 wbcErr wbcQueryGidToSid(gid_t gid,
                        struct wbcDomainSid *sid)
 {
        return WBC_ERR_NOT_IMPLEMENTED;
 }
 
-/** @brief Obtain a new uid from Winbind
- *
- * @param *puid      *pointer to the allocated uid
- *
- * @return #wbcErr
- **/
-
+/* Obtain a new uid from Winbind */
 wbcErr wbcAllocateUid(uid_t *puid)
 {
        struct winbindd_request request;
@@ -296,13 +235,7 @@ wbcErr wbcAllocateUid(uid_t *puid)
        return wbc_status;
 }
 
-/** @brief Obtain a new gid from Winbind
- *
- * @param *pgid      Pointer to the allocated gid
- *
- * @return #wbcErr
- **/
-
+/* Obtain a new gid from Winbind */
 wbcErr wbcAllocateGid(gid_t *pgid)
 {
        struct winbindd_request request;
@@ -336,13 +269,7 @@ wbcErr wbcAllocateGid(gid_t *pgid)
 #define _ID_TYPE_UID 1
 #define _ID_TYPE_GID 2
 
-/** @brief Set an user id mapping
- *
- * @param uid       Uid of the desired mapping.
- * @param *sid      Pointer to the sid of the diresired mapping.
- *
- * @return #wbcErr
- **/
+/* Set an user id mapping */
 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid)
 {
        struct winbindd_request request;
@@ -379,13 +306,7 @@ wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid)
        return wbc_status;
 }
 
-/** @brief Set a group id mapping
- *
- * @param gid       Gid of the desired mapping.
- * @param *sid      Pointer to the sid of the diresired mapping.
- *
- * @return #wbcErr
- **/
+/* Set a group id mapping */
 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid)
 {
        struct winbindd_request request;
@@ -422,13 +343,7 @@ wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid)
        return wbc_status;
 }
 
-/** @brief Remove a user id mapping
- *
- * @param uid       Uid of the mapping to remove.
- * @param *sid      Pointer to the sid of the mapping to remove.
- *
- * @return #wbcErr
- **/
+/* Remove a user id mapping */
 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid)
 {
        struct winbindd_request request;
@@ -465,13 +380,7 @@ wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid)
        return wbc_status;
 }
 
-/** @brief Remove a group id mapping
- *
- * @param gid       Gid of the mapping to remove.
- * @param *sid      Pointer to the sid of the mapping to remove.
- *
- * @return #wbcErr
- **/
+/* Remove a group id mapping */
 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid)
 {
        struct winbindd_request request;
@@ -508,12 +417,7 @@ wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid)
        return wbc_status;
 }
 
-/** @brief Set the highwater mark for allocated uids.
- *
- * @param uid_hwm      The new uid highwater mark value
- *
- * @return #wbcErr
- **/
+/* Set the highwater mark for allocated uids. */
 wbcErr wbcSetUidHwm(uid_t uid_hwm)
 {
        struct winbindd_request request;
@@ -538,12 +442,7 @@ wbcErr wbcSetUidHwm(uid_t uid_hwm)
        return wbc_status;
 }
 
-/** @brief Set the highwater mark for allocated gids.
- *
- * @param gid_hwm      The new gid highwater mark value
- *
- * @return #wbcErr
- **/
+/* Set the highwater mark for allocated gids. */
 wbcErr wbcSetGidHwm(gid_t gid_hwm)
 {
        struct winbindd_request request;
index 401d2ad..92c6643 100644 (file)
 
 #include "libwbclient.h"
 
-/** @brief Authenticate a username/password pair
- *
- * @param username     Name of user to authenticate
- * @param password     Clear text password os user
- *
- * @return #wbcErr
- **/
-
+/* Authenticate a username/password pair */
 wbcErr wbcAuthenticateUser(const char *username,
                           const char *password)
 {
@@ -305,16 +298,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Authenticate with more detailed information
- *
- * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
- *                     is not supported yet
- * @param info         Output details on WBC_ERR_SUCCESS
- * @param error        Output details on WBC_ERR_AUTH_ERROR
- *
- * @return #wbcErr
- **/
-
+/* Authenticate with more detailed information */
 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
                             struct wbcAuthUserInfo **info,
                             struct wbcAuthErrorInfo **error)
@@ -496,16 +480,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Trigger a verification of the trust credentials of a specific domain
- *
- * @param *domain      The name of the domain, only NULL for the default domain is
- *                     supported yet. Other values than NULL will result in
- *                     WBC_ERR_NOT_IMPLEMENTED.
- * @param error        Output details on WBC_ERR_AUTH_ERROR
- *
- * @return #wbcErr
- *
- **/
+/* Trigger a verification of the trust credentials of a specific domain */
 wbcErr wbcCheckTrustCredentials(const char *domain,
                                struct wbcAuthErrorInfo **error)
 {
@@ -547,15 +522,7 @@ wbcErr wbcCheckTrustCredentials(const char *domain,
        return wbc_status;
 }
 
-/** @brief Trigger an extended logoff notification to Winbind for a specific user
- *
- * @param params      A wbcLogoffUserParams structure
- * @param error       User output details on error
- *
- * @return #wbcErr
- *
- **/
-
+/* Trigger an extended logoff notification to Winbind for a specific user */
 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
                       struct wbcAuthErrorInfo **error)
 {
@@ -642,18 +609,7 @@ wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
        return wbc_status;
 }
 
-/** @brief Trigger a logoff notification to Winbind for a specific user
- *
- * @param username    Name of user to remove from Winbind's list of
- *                    logged on users.
- * @param uid         Uid assigned to the username
- * @param ccfilename  Absolute path to the Krb5 credentials cache to
- *                    be removed
- *
- * @return #wbcErr
- *
- **/
-
+/* Trigger a logoff notification to Winbind for a specific user */
 wbcErr wbcLogoffUser(const char *username,
                     uid_t uid,
                     const char *ccfilename)
@@ -693,16 +649,7 @@ wbcErr wbcLogoffUser(const char *username,
        return wbc_status;
 }
 
-/** @brief Change a password for a user with more detailed information upon
- *        failure
- * @param params                Input parameters
- * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
- * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
- * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
- *
- * @return #wbcErr
- **/
-
+/* Change a password for a user with more detailed information upon failure */
 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
                               struct wbcAuthErrorInfo **error,
                               enum wbcPasswordChangeRejectReason *reject_reason,
@@ -907,15 +854,7 @@ wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
        return wbc_status;
 }
 
-/** @brief Change a password for a user
- *
- * @param username             Name of user to authenticate
- * @param old_password         Old clear text password of user
- * @param new_password         New clear text password of user
- *
- * @return #wbcErr
- **/
-
+/* Change a password for a user */
 wbcErr wbcChangeUserPassword(const char *username,
                             const char *old_password,
                             const char *new_password)
@@ -940,17 +879,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Logon a User
- *
- * @param[in]  params      Pointer to a wbcLogonUserParams structure
- * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
- * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
- * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
- *
- * @return #wbcErr
- *
- **/
-
+/* Logon a User */
 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
                    struct wbcLogonUserInfo **info,
                    struct wbcAuthErrorInfo **error,
@@ -1096,14 +1025,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Authenticate a user with cached credentials
- *
- * @param *params    Pointer to a wbcCredentialCacheParams structure
- * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
- * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
- *
- * @return #wbcErr
- **/
+/* Authenticate a user with cached credentials */
 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
                           struct wbcCredentialCacheInfo **info,
                           struct wbcAuthErrorInfo **error)
index d54a5af..cd94599 100644 (file)
@@ -126,15 +126,7 @@ done:
        return grp;
 }
 
-/** @brief Fill in a struct passwd* for a domain user based
- *   on username
- *
- * @param *name     Username to lookup
- * @param **pwd     Pointer to resulting struct passwd* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Fill in a struct passwd* for a domain user based on username */
 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -167,15 +159,7 @@ wbcErr wbcGetpwnam(const char *name, struct passwd **pwd)
        return wbc_status;
 }
 
-/** @brief Fill in a struct passwd* for a domain user based
- *   on uid
- *
- * @param uid       Uid to lookup
- * @param **pwd     Pointer to resulting struct passwd* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Fill in a struct passwd* for a domain user based on uid */
 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -206,15 +190,7 @@ wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd)
        return wbc_status;
 }
 
-/** @brief Fill in a struct passwd* for a domain user based
- *   on username
- *
- * @param *name     Username to lookup
- * @param **grp     Pointer to resulting struct group* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Fill in a struct passwd* for a domain user based on username */
 wbcErr wbcGetgrnam(const char *name, struct group **grp)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -251,15 +227,7 @@ wbcErr wbcGetgrnam(const char *name, struct group **grp)
        return wbc_status;
 }
 
-/** @brief Fill in a struct passwd* for a domain user based
- *   on uid
- *
- * @param gid       Uid to lookup
- * @param **grp     Pointer to resulting struct group* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Fill in a struct passwd* for a domain user based on uid */
 wbcErr wbcGetgrgid(gid_t gid, struct group **grp)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -309,11 +277,7 @@ static uint32_t pw_cache_idx;
  */
 static struct winbindd_response pw_response;
 
-/** @brief Reset the passwd iterator
- *
- * @return #wbcErr
- **/
-
+/* Reset the passwd iterator */
 wbcErr wbcSetpwent(void)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -335,11 +299,7 @@ wbcErr wbcSetpwent(void)
        return wbc_status;
 }
 
-/** @brief Close the passwd iterator
- *
- * @return #wbcErr
- **/
-
+/* Close the passwd iterator */
 wbcErr wbcEndpwent(void)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -359,13 +319,7 @@ wbcErr wbcEndpwent(void)
        return wbc_status;
 }
 
-/** @brief Return the next struct passwd* entry from the pwent iterator
- *
- * @param **pwd       Pointer to resulting struct passwd* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Return the next struct passwd* entry from the pwent iterator */
 wbcErr wbcGetpwent(struct passwd **pwd)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -425,11 +379,7 @@ static uint32_t gr_cache_idx;
  */
 static struct winbindd_response gr_response;
 
-/** @brief Reset the group iterator
- *
- * @return #wbcErr
- **/
-
+/* Reset the group iterator */
 wbcErr wbcSetgrent(void)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -451,11 +401,7 @@ wbcErr wbcSetgrent(void)
        return wbc_status;
 }
 
-/** @brief Close the group iterator
- *
- * @return #wbcErr
- **/
-
+/* Close the group iterator */
 wbcErr wbcEndgrent(void)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -475,13 +421,7 @@ wbcErr wbcEndgrent(void)
        return wbc_status;
 }
 
-/** @brief Return the next struct group* entry from the pwent iterator
- *
- * @param **grp       Pointer to resulting struct group* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Return the next struct group* entry from the pwent iterator */
 wbcErr wbcGetgrent(struct group **grp)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -531,15 +471,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Return the next struct group* entry from the pwent iterator
- *
- * This is similar to #wbcGetgrent, just that the member list is empty
- *
- * @param **grp       Pointer to resulting struct group* from the query.
- *
- * @return #wbcErr
- **/
-
+/* Return the next struct group* entry from the pwent iterator */
 wbcErr wbcGetgrlist(struct group **grp)
 {
        wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE;
@@ -584,14 +516,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Return the unix group array belonging to the given user
- *
- * @param *account       The given user name
- * @param *num_groups    Number of elements returned in the groups array
- * @param **_groups      Pointer to resulting gid_t array.
- *
- * @return #wbcErr
- **/
+/* Return the unix group array belonging to the given user */
 wbcErr wbcGetGroups(const char *account,
                    uint32_t *num_groups,
                    gid_t **_groups)
index 92de22e..e2157b9 100644 (file)
 #include "libwbclient.h"
 
 
-/** @brief Convert a binary SID to a character string
- *
- * @param sid           Binary Security Identifier
- * @param **sid_string  Resulting character string
- *
- * @return #wbcErr
- **/
-
+/* Convert a binary SID to a character string */
 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
                      char **sid_string)
 {
@@ -73,14 +66,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Convert a character string to a binary SID
- *
- * @param *str          Character string in the form of S-...
- * @param sid           Resulting binary SID
- *
- * @return #wbcErr
- **/
-
+/* Convert a character string to a binary SID */
 wbcErr wbcStringToSid(const char *str,
                      struct wbcDomainSid *sid)
 {
@@ -163,17 +149,7 @@ done:
 
 }
 
-/** @brief Convert a domain and name to SID
- *
- * @param domain      Domain name (possibly "")
- * @param name        User or group name
- * @param *sid        Pointer to the resolved domain SID
- * @param *name_type  Pointer to the SID type
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a domain and name to SID */
 wbcErr wbcLookupName(const char *domain,
                     const char *name,
                     struct wbcDomainSid *sid,
@@ -216,17 +192,7 @@ wbcErr wbcLookupName(const char *domain,
        return wbc_status;
 }
 
-/** @brief Convert a SID to a domain and name
- *
- * @param *sid        Pointer to the domain SID to be resolved
- * @param pdomain     Resolved Domain name (possibly "")
- * @param pname       Resolved User or group name
- * @param *pname_type Pointer to the resolved SID type
- *
- * @return #wbcErr
- *
- **/
-
+/* Convert a SID to a domain and name */
 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
                    char **pdomain,
                    char **pname,
@@ -310,9 +276,7 @@ wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
        return wbc_status;
 }
 
-/** @brief Translate a collection of RIDs within a domain to names
- *
- **/
+/* Translate a collection of RIDs within a domain to names */
 
 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
                     int num_rids,
@@ -448,10 +412,7 @@ wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
        return wbc_status;
 }
 
-/** @brief Get the groups a user belongs to
- *
- **/
-
+/* Get the groups a user belongs to */
 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
                         bool domain_groups_only,
                         uint32_t *num_sids,
@@ -530,10 +491,7 @@ wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
        return wbc_status;
 }
 
-/** @brief Lists Users
- *
- **/
-
+/* Lists Users */
 wbcErr wbcListUsers(const char *domain_name,
                    uint32_t *_num_users,
                    const char ***_users)
@@ -601,10 +559,7 @@ wbcErr wbcListUsers(const char *domain_name,
        return wbc_status;
 }
 
-/** @brief Lists Groups
- *
- **/
-
+/* Lists Groups */
 wbcErr wbcListGroups(const char *domain_name,
                     uint32_t *_num_groups,
                     const char ***_groups)
index b486874..7cfb64b 100644 (file)
@@ -119,16 +119,7 @@ done:
 }
 
 
-/** @brief Lookup the current status of a trusted domain
- *
- * @param domain      Domain to query
- * @param *dinfo       Pointer to returned domain_info struct
- *
- * @return #wbcErr
- *
- **/
-
-
+/* Lookup the current status of a trusted domain */
 wbcErr wbcDomainInfo(const char *domain, struct wbcDomainInfo **dinfo)
 {
        struct winbindd_request request;
@@ -189,14 +180,7 @@ wbcErr wbcDomainInfo(const char *domain, struct wbcDomainInfo **dinfo)
 }
 
 
-/** @brief Resolve a NetbiosName via WINS
- *
- * @param name         Name to resolve
- * @param *ip          Pointer to the ip address string
- *
- * @return #wbcErr
- *
- **/
+/* Resolve a NetbiosName via WINS */
 wbcErr wbcResolveWinsByName(const char *name, char **ip)
 {
        struct winbindd_request request;
@@ -229,14 +213,7 @@ wbcErr wbcResolveWinsByName(const char *name, char **ip)
        return wbc_status;
 }
 
-/** @brief Resolve an IP address via WINS into a NetbiosName
- *
- * @param ip          The ip address string
- * @param *name       Pointer to the name
- *
- * @return #wbcErr
- *
- **/
+/* Resolve an IP address via WINS into a NetbiosName */
 wbcErr wbcResolveWinsByIP(const char *ip, char **name)
 {
        struct winbindd_request request;
@@ -401,14 +378,7 @@ static wbcErr process_domain_info_string(TALLOC_CTX *ctx,
        return wbc_status;
 }
 
-/** @brief Enumerate the domain trusts known by Winbind
- *
- * @param **domains     Pointer to the allocated domain list array
- * @param *num_domains  Pointer to number of domains returned
- *
- * @return #wbcErr
- *
- **/
+/* Enumerate the domain trusts known by Winbind */
 wbcErr wbcListTrusts(struct wbcDomainInfo **domains, size_t *num_domains)
 {
        struct winbindd_response response;
@@ -493,18 +463,7 @@ wbcErr wbcListTrusts(struct wbcDomainInfo **domains, size_t *num_domains)
        return wbc_status;
 }
 
-/** @brief Enumerate the domain trusts known by Winbind
- *
- * @param domain        Name of the domain to query for a DC
- * @param flags         Bit flags used to control the domain location query
- * @param *dc_info      Pointer to the returned domain controller information
- *
- * @return #wbcErr
- *
- **/
-
-
-
+/* Enumerate the domain trusts known by Winbind */
 wbcErr wbcLookupDomainController(const char *domain,
                                 uint32_t flags,
                                struct wbcDomainControllerInfo **dc_info)
@@ -617,18 +576,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Get extended domain controller information
- *
- * @param domain        Name of the domain to query for a DC
- * @param guid          Guid of the domain to query for a DC
- * @param site          Site of the domain to query for a DC
- * @param flags         Bit flags used to control the domain location query
- * @param *dc_info      Pointer to the returned extended domain controller information
- *
- * @return #wbcErr
- *
- **/
-
+/* Get extended domain controller information */
 wbcErr wbcLookupDomainControllerEx(const char *domain,
                                   struct wbcGuid *guid,
                                   const char *site,
@@ -690,19 +638,7 @@ done:
        return wbc_status;
 }
 
-/** @brief Initialize a named blob and add to list of blobs
- *
- * @param[in,out] num_blobs     Pointer to the number of blobs
- * @param[in,out] blobs         Pointer to an array of blobs
- * @param[in]     name          Name of the new named blob
- * @param[in]     flags         Flags of the new named blob
- * @param[in]     data          Blob data of new blob
- * @param[in]     length        Blob data length of new blob
- *
- * @return #wbcErr
- *
- **/
-
+/* Initialize a named blob and add to list of blobs */
 wbcErr wbcAddNamedBlob(size_t *num_blobs,
                       struct wbcNamedBlob **blobs,
                       const char *name,
index c0b7e06..3a9afad 100644 (file)
@@ -123,13 +123,7 @@ const char *wbcErrorString(wbcErr error)
        return "unknown wbcErr value";
 }
 
-/** @brief Free library allocated memory
- *
- * @param *p Pointer to free
- *
- * @return void
- **/
-
+/* Free library allocated memory */
 void wbcFreeMemory(void *p)
 {
        if (p)
index cb31360..fcad3ff 100644 (file)
@@ -486,10 +486,17 @@ struct wbcDomainControllerInfoEx {
        const char *client_site_name;
 };
 
-/*
+/**********************************************************
  * Memory Management
- */
+ **********************************************************/
 
+/**
+ * @brief Free library allocated memory
+ *
+ * @param *p Pointer to free
+ *
+ * @return void
+ **/
 void wbcFreeMemory(void*);
 
 
@@ -497,9 +504,25 @@ void wbcFreeMemory(void*);
  * Utility functions for dealing with SIDs
  */
 
+/**
+ * @brief Convert a binary SID to a character string
+ *
+ * @param sid           Binary Security Identifier
+ * @param **sid_string  Resulting character string
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
                      char **sid_string);
 
+/**
+ * @brief Convert a character string to a binary SID
+ *
+ * @param *str          Character string in the form of S-...
+ * @param sid           Resulting binary SID
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcStringToSid(const char *sid_string,
                      struct wbcDomainSid *sid);
 
@@ -507,32 +530,76 @@ wbcErr wbcStringToSid(const char *sid_string,
  * Utility functions for dealing with GUIDs
  */
 
+/**
+ * @brief Convert a binary GUID to a character string
+ *
+ * @param guid           Binary Guid
+ * @param **guid_string  Resulting character string
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGuidToString(const struct wbcGuid *guid,
                       char **guid_string);
 
+/**
+ * @brief Convert a character string to a binary GUID
+ *
+ * @param *str          Character string
+ * @param guid          Resulting binary GUID
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcStringToGuid(const char *guid_string,
                       struct wbcGuid *guid);
 
+/**
+ * @brief Ping winbindd to see if the daemon is running
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcPing(void);
 
 wbcErr wbcLibraryDetails(struct wbcLibraryDetails **details);
 
 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
 
-/*
+/**********************************************************
  * Name/SID conversion
- */
+ **********************************************************/
 
+/**
+ * @brief Convert a domain and name to SID
+ *
+ * @param domain      Domain name (possibly "")
+ * @param name        User or group name
+ * @param *sid        Pointer to the resolved domain SID
+ * @param *name_type  Pointer to the SID type
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLookupName(const char *dom_name,
                     const char *name,
                     struct wbcDomainSid *sid,
                     enum wbcSidType *name_type);
 
+/**
+ * @brief Convert a SID to a domain and name
+ *
+ * @param *sid        Pointer to the domain SID to be resolved
+ * @param pdomain     Resolved Domain name (possibly "")
+ * @param pname       Resolved User or group name
+ * @param *pname_type Pointer to the resolved SID type
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
                    char **domain,
                    char **name,
                    enum wbcSidType *name_type);
 
+/**
+ * @brief Translate a collection of RIDs within a domain to names
+ */
 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
                     int num_rids,
                     uint32_t *rids,
@@ -540,15 +607,24 @@ wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
                     const char ***names,
                     enum wbcSidType **types);
 
+/*
+ * @brief Get the groups a user belongs to
+ **/
 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
                         bool domain_groups_only,
                         uint32_t *num_sids,
                         struct wbcDomainSid **sids);
 
+/**
+ * @brief Lists Users
+ **/
 wbcErr wbcListUsers(const char *domain_name,
                    uint32_t *num_users,
                    const char ***users);
 
+/**
+ * @brief Lists Groups
+ **/
 wbcErr wbcListGroups(const char *domain_name,
                     uint32_t *num_groups,
                     const char ***groups);
@@ -558,88 +634,324 @@ wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid,
                         char **pfullname,
                         enum wbcSidType *pname_type);
 
-/*
+/**********************************************************
  * SID/uid/gid Mappings
- */
+ **********************************************************/
 
+/**
+ * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
+ *
+ * @param *sid        Pointer to the domain SID to be resolved
+ * @param *puid       Pointer to the resolved uid_t value
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
                   uid_t *puid);
 
+/**
+ * @brief Convert a Windows SID to a Unix uid if there already is a mapping
+ *
+ * @param *sid        Pointer to the domain SID to be resolved
+ * @param *puid       Pointer to the resolved uid_t value
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
                        uid_t *puid);
 
+/**
+ * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
+ *
+ * @param uid         Unix uid to be resolved
+ * @param *sid        Pointer to the resolved domain SID
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcUidToSid(uid_t uid,
                   struct wbcDomainSid *sid);
 
+/**
+ * @brief Convert a Unix uid to a Windows SID if there already is a mapping
+ *
+ * @param uid         Unix uid to be resolved
+ * @param *sid        Pointer to the resolved domain SID
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcQueryUidToSid(uid_t uid,
                        struct wbcDomainSid *sid);
 
+/**
+ * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
+ *
+ * @param *sid        Pointer to the domain SID to be resolved
+ * @param *pgid       Pointer to the resolved gid_t value
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
                   gid_t *pgid);
 
+/**
+ * @brief Convert a Windows SID to a Unix gid if there already is a mapping
+ *
+ * @param *sid        Pointer to the domain SID to be resolved
+ * @param *pgid       Pointer to the resolved gid_t value
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
                        gid_t *pgid);
 
+/**
+ * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
+ *
+ * @param gid         Unix gid to be resolved
+ * @param *sid        Pointer to the resolved domain SID
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcGidToSid(gid_t gid,
                   struct wbcDomainSid *sid);
 
+/**
+ * @brief Convert a Unix gid to a Windows SID if there already is a mapping
+ *
+ * @param gid         Unix gid to be resolved
+ * @param *sid        Pointer to the resolved domain SID
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcQueryGidToSid(gid_t gid,
                        struct wbcDomainSid *sid);
 
+/**
+ * @brief Obtain a new uid from Winbind
+ *
+ * @param *puid      *pointer to the allocated uid
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcAllocateUid(uid_t *puid);
 
+/**
+ * @brief Obtain a new gid from Winbind
+ *
+ * @param *pgid      Pointer to the allocated gid
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcAllocateGid(gid_t *pgid);
 
+/**
+ * @brief Set an user id mapping
+ *
+ * @param uid       Uid of the desired mapping.
+ * @param *sid      Pointer to the sid of the diresired mapping.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 
+/**
+ * @brief Set a group id mapping
+ *
+ * @param gid       Gid of the desired mapping.
+ * @param *sid      Pointer to the sid of the diresired mapping.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 
+/**
+ * @brief Remove a user id mapping
+ *
+ * @param uid       Uid of the mapping to remove.
+ * @param *sid      Pointer to the sid of the mapping to remove.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 
+/**
+ * @brief Remove a group id mapping
+ *
+ * @param gid       Gid of the mapping to remove.
+ * @param *sid      Pointer to the sid of the mapping to remove.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 
+/**
+ * @brief Set the highwater mark for allocated uids.
+ *
+ * @param uid_hwm      The new uid highwater mark value
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSetUidHwm(uid_t uid_hwm);
 
+/**
+ * @brief Set the highwater mark for allocated gids.
+ *
+ * @param gid_hwm      The new gid highwater mark value
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSetGidHwm(gid_t gid_hwm);
 
-/*
+/**********************************************************
  * NSS Lookup User/Group details
- */
+ **********************************************************/
 
+/**
+ * @brief Fill in a struct passwd* for a domain user based
+ *   on username
+ *
+ * @param *name     Username to lookup
+ * @param **pwd     Pointer to resulting struct passwd* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
 
+/**
+ * @brief Fill in a struct passwd* for a domain user based
+ *   on uid
+ *
+ * @param uid       Uid to lookup
+ * @param **pwd     Pointer to resulting struct passwd* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
 
+/**
+ * @brief Fill in a struct passwd* for a domain user based
+ *   on username
+ *
+ * @param *name     Username to lookup
+ * @param **grp     Pointer to resulting struct group* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetgrnam(const char *name, struct group **grp);
 
+/**
+ * @brief Fill in a struct passwd* for a domain user based
+ *   on uid
+ *
+ * @param gid       Uid to lookup
+ * @param **grp     Pointer to resulting struct group* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
 
+/**
+ * @brief Reset the passwd iterator
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSetpwent(void);
 
+/**
+ * @brief Close the passwd iterator
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcEndpwent(void);
 
+/**
+ * @brief Return the next struct passwd* entry from the pwent iterator
+ *
+ * @param **pwd       Pointer to resulting struct passwd* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetpwent(struct passwd **pwd);
 
+/**
+ * @brief Reset the group iterator
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcSetgrent(void);
 
+/**
+ * @brief Close the group iterator
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcEndgrent(void);
 
+/**
+ * @brief Return the next struct group* entry from the pwent iterator
+ *
+ * @param **grp       Pointer to resulting struct group* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetgrent(struct group **grp);
 
+/**
+ * @brief Return the next struct group* entry from the pwent iterator
+ *
+ * This is similar to #wbcGetgrent, just that the member list is empty
+ *
+ * @param **grp       Pointer to resulting struct group* from the query.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetgrlist(struct group **grp);
 
+/**
+ * @brief Return the unix group array belonging to the given user
+ *
+ * @param *account       The given user name
+ * @param *num_groups    Number of elements returned in the groups array
+ * @param **_groups      Pointer to resulting gid_t array.
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcGetGroups(const char *account,
                    uint32_t *num_groups,
                    gid_t **_groups);
 
 
-/*
+/**********************************************************
  * Lookup Domain information
- */
+ **********************************************************/
 
+/**
+ * @brief Lookup the current status of a trusted domain
+ *
+ * @param domain      Domain to query
+ * @param *dinfo       Pointer to returned domain_info struct
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcDomainInfo(const char *domain,
                     struct wbcDomainInfo **info);
 
+/**
+ * @brief Enumerate the domain trusts known by Winbind
+ *
+ * @param **domains     Pointer to the allocated domain list array
+ * @param *num_domains  Pointer to number of domains returned
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcListTrusts(struct wbcDomainInfo **domains, 
                     size_t *num_domains);
 
@@ -665,66 +977,206 @@ wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
 
+/**
+ * @brief Enumerate the domain trusts known by Winbind
+ *
+ * @param domain        Name of the domain to query for a DC
+ * @param flags         Bit flags used to control the domain location query
+ * @param *dc_info      Pointer to the returned domain controller information
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLookupDomainController(const char *domain,
                                 uint32_t flags,
                                 struct wbcDomainControllerInfo **dc_info);
 
+/**
+ * @brief Get extended domain controller information
+ *
+ * @param domain        Name of the domain to query for a DC
+ * @param guid          Guid of the domain to query for a DC
+ * @param site          Site of the domain to query for a DC
+ * @param flags         Bit flags used to control the domain location query
+ * @param *dc_info      Pointer to the returned extended domain controller information
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLookupDomainControllerEx(const char *domain,
                                   struct wbcGuid *guid,
                                   const char *site,
                                   uint32_t flags,
                                   struct wbcDomainControllerInfoEx **dc_info);
 
-/*
+/**********************************************************
  * Athenticate functions
- */
+ **********************************************************/
 
+/**
+ * @brief Authenticate a username/password pair
+ *
+ * @param username     Name of user to authenticate
+ * @param password     Clear text password os user
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcAuthenticateUser(const char *username,
                           const char *password);
 
+/**
+ * @brief Authenticate with more detailed information
+ *
+ * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
+ *                     is not supported yet
+ * @param info         Output details on WBC_ERR_SUCCESS
+ * @param error        Output details on WBC_ERR_AUTH_ERROR
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
                             struct wbcAuthUserInfo **info,
                             struct wbcAuthErrorInfo **error);
 
+/**
+ * @brief Logon a User
+ *
+ * @param[in]  params      Pointer to a wbcLogonUserParams structure
+ * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
+ * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
+ * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
                    struct wbcLogonUserInfo **info,
                    struct wbcAuthErrorInfo **error,
                    struct wbcUserPasswordPolicyInfo **policy);
 
+/**
+ * @brief Trigger a logoff notification to Winbind for a specific user
+ *
+ * @param username    Name of user to remove from Winbind's list of
+ *                    logged on users.
+ * @param uid         Uid assigned to the username
+ * @param ccfilename  Absolute path to the Krb5 credentials cache to
+ *                    be removed
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLogoffUser(const char *username,
                     uid_t uid,
                     const char *ccfilename);
 
+/**
+ * @brief Trigger an extended logoff notification to Winbind for a specific user
+ *
+ * @param params      A wbcLogoffUserParams structure
+ * @param error       User output details on error
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
                       struct wbcAuthErrorInfo **error);
 
+/**
+ * @brief Change a password for a user
+ *
+ * @param username      Name of user to authenticate
+ * @param old_password  Old clear text password of user
+ * @param new_password  New clear text password of user
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcChangeUserPassword(const char *username,
                             const char *old_password,
                             const char *new_password);
 
+/**
+ * @brief Change a password for a user with more detailed information upon
+ *   failure
+ *
+ * @param params                Input parameters
+ * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
+ * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
+ * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
                               struct wbcAuthErrorInfo **error,
                               enum wbcPasswordChangeRejectReason *reject_reason,
                               struct wbcUserPasswordPolicyInfo **policy);
 
+/**
+ * @brief Authenticate a user with cached credentials
+ *
+ * @param *params    Pointer to a wbcCredentialCacheParams structure
+ * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
+ * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
                           struct wbcCredentialCacheInfo **info,
                           struct wbcAuthErrorInfo **error);
 
-/*
+/**********************************************************
  * Resolve functions
- */
+ **********************************************************/
+
+/**
+ * @brief Resolve a NetbiosName via WINS
+ *
+ * @param name         Name to resolve
+ * @param *ip          Pointer to the ip address string
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcResolveWinsByName(const char *name, char **ip);
+
+/**
+ * @brief Resolve an IP address via WINS into a NetbiosName
+ *
+ * @param ip          The ip address string
+ * @param *name       Pointer to the name
+ *
+ * @return #wbcErr
+ *
+ **/
 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
 
-/*
+/**********************************************************
  * Trusted domain functions
- */
+ **********************************************************/
+
+/**
+ * @brief Trigger a verification of the trust credentials of a specific domain
+ *
+ * @param *domain      The name of the domain, only NULL for the default domain is
+ *                     supported yet. Other values than NULL will result in
+ *                     WBC_ERR_NOT_IMPLEMENTED.
+ * @param error        Output details on WBC_ERR_AUTH_ERROR
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcCheckTrustCredentials(const char *domain,
                                struct wbcAuthErrorInfo **error);
-/*
+
+/**********************************************************
  * Helper functions
- */
+ **********************************************************/
+
+/**
+ * @brief Initialize a named blob and add to list of blobs
+ *
+ * @param[in,out] num_blobs     Pointer to the number of blobs
+ * @param[in,out] blobs         Pointer to an array of blobs
+ * @param[in]     name          Name of the new named blob
+ * @param[in]     flags         Flags of the new named blob
+ * @param[in]     data          Blob data of new blob
+ * @param[in]     length        Blob data length of new blob
+ *
+ * @return #wbcErr
+ **/
 wbcErr wbcAddNamedBlob(size_t *num_blobs,
                       struct wbcNamedBlob **blobs,
                       const char *name,