From: Arran Cudbard-Bell <a.cudbardb@freeradius.org>
Date: Sun, 14 Jun 2015 01:54:40 +0000 (-0400)
Subject: Sync function docs in rlm_ldap with v3.1.x
X-Git-Tag: release_3_0_9~183
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=939842e753e1bd040396d819e4f51674baa53dea;p=thirdparty%2Ffreeradius-server.git

Sync function docs in rlm_ldap with v3.1.x
---

diff --git a/src/modules/rlm_ldap/attrmap.c b/src/modules/rlm_ldap/attrmap.c
index 6d43e7323f9..07bf5e0b661 100644
--- a/src/modules/rlm_ldap/attrmap.c
+++ b/src/modules/rlm_ldap/attrmap.c
@@ -295,7 +295,9 @@ int rlm_ldap_map_expand(rlm_ldap_map_exp_t *expanded, REQUEST *request, vp_map_t
  * @param[in] handle associated with entry.
  * @param[in] expanded attributes (rhs of map).
  * @param[in] entry to retrieve attributes from.
- * @return number of maps successfully applied, or -1 on error.
+ * @return
+ *	- Number of maps successfully applied.
+ *	- -1 on failure.
  */
 int rlm_ldap_map_do(const rlm_ldap_t *inst, REQUEST *request, LDAP *handle,
 		    rlm_ldap_map_exp_t const *expanded, LDAPMessage *entry)
diff --git a/src/modules/rlm_ldap/clients.c b/src/modules/rlm_ldap/clients.c
index 272e8c9e6f4..4566fbe581b 100644
--- a/src/modules/rlm_ldap/clients.c
+++ b/src/modules/rlm_ldap/clients.c
@@ -38,7 +38,9 @@
  * @param[out] values array of char pointers.
  * @param[in,out] idx records current array offset.
  * @param[in] cs to iterate over.
- * @return 0 on success else -1 on error.
+ * @return
+ *	- 0 on success.
+ *	- -1 on failure.
  */
 static int rlm_ldap_client_get_attrs(char const **values, int *idx, CONF_SECTION const *cs)
 {
@@ -93,7 +95,9 @@ static int _get_client_value(char **out, CONF_PAIR const *cp, void *data)
  * @param[in] inst rlm_ldap configuration.
  * @param[in] tmpl to use as the base for the new client.
  * @param[in] map to load client attribute/LDAP attribute mappings from.
- * @return -1 on error else 0.
+ * @return
+ *	- 0 on success.
+ *	- -1 on failure.
  */
 int rlm_ldap_client_load(rlm_ldap_t const *inst, CONF_SECTION *tmpl, CONF_SECTION *map)
 {
diff --git a/src/modules/rlm_ldap/edir.c b/src/modules/rlm_ldap/edir.c
index 3f720f74fee..ddac7e226a1 100644
--- a/src/modules/rlm_ldap/edir.c
+++ b/src/modules/rlm_ldap/edir.c
@@ -63,7 +63,9 @@ RCSID("$Id$")
  *
  * @param[out] request_bv where to write the request BER value (must be freed with ber_bvfree).
  * @param[in] dn to query for.
- * @return 0 on success, and < 0 on error.
+ * @return
+ *	- 0 on success.
+ *	- < 0 on error.
  */
 static int ber_encode_request_data(char const *dn, struct berval **request_bv)
 {
@@ -119,7 +121,9 @@ finish:
  * @param[out] server_version that responded.
  * @param[out] out data.
  * @param[out] outlen Length of data written to out.
- * @return 0 on success, and < 0 on error.
+ * @return
+ *	- 0 on success.
+ *	- < 0 on error.
  */
 static int ber_decode_login_data(struct berval *reply_bv, int *server_version, void *out, size_t *outlen)
 {
@@ -154,7 +158,9 @@ finish:
  * @param[in] dn of user we want to retrieve the password for.
  * @param[out] password Where to write the retrieved password.
  * @param[out] passlen Length of data written to the password buffer.
- * @return 0 on success and < 0 on failure.
+ * @return
+ *	- 0 on success.
+ *	- < 0 on failure.
  */
 int nmasldap_get_password(LDAP *ld, char const *dn, char *password, size_t *passlen)
 {
diff --git a/src/modules/rlm_ldap/ldap.c b/src/modules/rlm_ldap/ldap.c
index 7ccb4878365..8c495c0f06a 100644
--- a/src/modules/rlm_ldap/ldap.c
+++ b/src/modules/rlm_ldap/ldap.c
@@ -98,7 +98,9 @@ size_t rlm_ldap_escape_func(UNUSED REQUEST *request, char *out, size_t outlen, c
  *
  * @param[in] in Str to check.
  * @param[in] inlen Length of string to check.
- * @return true if string looks like a DN, else false.
+ * @return
+ *	- true if string looks like a DN.
+ *	- false if string does not look like DN.
  */
 bool rlm_ldap_is_dn(char const *in, size_t inlen)
 {
@@ -303,7 +305,9 @@ size_t rlm_ldap_normalise_dn(char *out, char const *in)
  *
  * @param full DN.
  * @param part Partial DN as returned by ldap_parse_result.
- * @return the length of the portion of full which wasn't matched or -1 on error.
+ * @return
+ *	- Length of the portion of full which wasn't matched
+ *	- -1 on failure.
  */
 static size_t rlm_ldap_common_dn(char const *full, char const *part)
 {
@@ -445,7 +449,7 @@ char const *rlm_ldap_error_str(ldap_handle_t const *conn)
  * @param[out] error Where to write the error string, may be NULL, must not be freed.
  * @param[out] extra Where to write additional error string to, may be NULL (faster) or must be freed
  *	(with talloc_free).
- * @return One of the LDAP_PROC_* codes.
+ * @return One of the LDAP_PROC_* (#ldap_rcode_t) values.
  */
 static ldap_rcode_t rlm_ldap_result(rlm_ldap_t const *inst, ldap_handle_t const *conn, int msgid, char const *dn,
 				    LDAPMessage **result, char const **error, char **extra)
@@ -499,7 +503,7 @@ static ldap_rcode_t rlm_ldap_result(rlm_ldap_t const *inst, ldap_handle_t const
 
 	/*
 	 *	Now retrieve the result and check for errors
-	 *	ldap_result returns -1 on error, and 0 on timeout
+	 *	ldap_result returns -1 on failure, and 0 on timeout
 	 */
 	lib_errno = ldap_result(conn->handle, msgid, 1, &tv, result);
 	if (lib_errno == 0) {
@@ -801,7 +805,7 @@ ldap_rcode_t rlm_ldap_bind(rlm_ldap_t const *inst, REQUEST *request, ldap_handle
  * @param[in] attrs to retrieve.
  * @param[in] serverctrls Search controls to pass to the server.  May be NULL.
  * @param[in] clientctrls Search controls for ldap_search.  May be NULL.
- * @return One of the LDAP_PROC_* values.
+ * @return One of the LDAP_PROC_* (#ldap_rcode_t) values.
  */
 ldap_rcode_t rlm_ldap_search(LDAPMessage **result, rlm_ldap_t const *inst, REQUEST *request,
 			     ldap_handle_t **pconn,
@@ -960,7 +964,7 @@ finish:
  * @param[in,out] pconn to use. May change as this function calls functions which auto re-connect.
  * @param[in] dn of the object to modify.
  * @param[in] mods to make, see 'man ldap_modify' for more information.
- * @return One of the LDAP_PROC_* values.
+ * @return One of the LDAP_PROC_* (#ldap_rcode_t) values.
  */
 ldap_rcode_t rlm_ldap_modify(rlm_ldap_t const *inst, REQUEST *request, ldap_handle_t **pconn,
 			     char const *dn, LDAPMod *mods[])
@@ -1228,7 +1232,9 @@ finish:
  * @param[in] request Current request.
  * @param[in] conn used to retrieve access attributes.
  * @param[in] entry retrieved by rlm_ldap_find_user or rlm_ldap_search.
- * @return RLM_MODULE_USERLOCK if the user was denied access, else RLM_MODULE_OK.
+ * @return
+ *	- #RLM_MODULE_USERLOCK if the user was denied access.
+ *	- #RLM_MODULE_OK otherwise.
  */
 rlm_rcode_t rlm_ldap_check_access(rlm_ldap_t const *inst, REQUEST *request,
 				  ldap_handle_t const *conn, LDAPMessage *entry)
diff --git a/src/modules/rlm_ldap/rlm_ldap.c b/src/modules/rlm_ldap/rlm_ldap.c
index e6b5a5aab0a..b5757a97734 100644
--- a/src/modules/rlm_ldap/rlm_ldap.c
+++ b/src/modules/rlm_ldap/rlm_ldap.c
@@ -351,7 +351,9 @@ free_urldesc:
  * @param check Which group to check for user membership.
  * @param check_pairs Unknown.
  * @param reply_pairs Unknown.
- * @return 1 on failure (or if the user is not a member), else 0.
+ * @return
+ *	- 1 on failure (or if the user is not a member).
+ *	- 0 on success.
  */
 static int rlm_ldap_groupcmp(void *instance, REQUEST *request, UNUSED VALUE_PAIR *thing, VALUE_PAIR *check,
 			     UNUSED VALUE_PAIR *check_pairs, UNUSED VALUE_PAIR **reply_pairs)
@@ -507,7 +509,9 @@ static int mod_detach(void *instance)
  * @param[in] parent of the config section.
  * @param[out] config to write the sub section parameters to.
  * @param[in] comp The section name were parsing the config for.
- * @return 0 on success, else < 0 on failure.
+ * @return
+ *	- 0 on success.
+ *	- < 0 on failure.
  */
 static int parse_sub_section(rlm_ldap_t *inst, CONF_SECTION *parent, ldap_acct_section_t **config,
 			     rlm_components_t comp)
@@ -542,7 +546,9 @@ static int parse_sub_section(rlm_ldap_t *inst, CONF_SECTION *parent, ldap_acct_s
  *
  * @param conf to parse.
  * @param instance configuration data.
- * @return 0 on success < 0 on failure.
+ * @return
+ *	- 0 on success.
+ *	- < 0 on failure.
  */
 static int mod_bootstrap(CONF_SECTION *conf, void *instance)
 {
@@ -612,7 +618,9 @@ static int mod_bootstrap(CONF_SECTION *conf, void *instance)
  *
  * @param conf to parse.
  * @param instance configuration data.
- * @return 0 on success < 0 on failure.
+ * @return
+ *	- 0 on success.
+ *	- < 0 on failure.
  */
 static int mod_instantiate(CONF_SECTION *conf, void *instance)
 {