From 717a19859f7a3a740eaeb9ba7a1666b982eb2436 Mon Sep 17 00:00:00 2001
From: Dmitry Podgorny <pasis.ua@gmail.com>
Date: Wed, 14 Sep 2016 18:54:40 +0300
Subject: [PATCH] doc: describe parameters to suppress doxygen warnings

---
 src/rand.h     | 7 +++++++
 src/resolver.h | 3 +++
 src/stanza.c   | 4 ++++
 src/uuid.c     | 3 +++
 4 files changed, 17 insertions(+)

diff --git a/src/rand.h b/src/rand.h
index 0a605c4..1e4880b 100644
--- a/src/rand.h
+++ b/src/rand.h
@@ -22,11 +22,15 @@
 typedef struct _xmpp_rand_t xmpp_rand_t;
 
 /** Create new xmpp_rand_t object.
+ *
+ *  @param ctx A Strophe context object
  *
  *  @ingroup Random
  */
 xmpp_rand_t *xmpp_rand_new(xmpp_ctx_t *ctx);
 /** Destroy an xmpp_rand_t object.
+ *
+ *  @param ctx A Strophe context object
  *
  *  @ingroup Random
  */
@@ -47,7 +51,10 @@ int xmpp_rand(xmpp_rand_t *rand);
 void xmpp_rand_bytes(xmpp_rand_t *rand, unsigned char *output, size_t len);
 
 /** Generate a nonce that is printable randomized string.
+ *  This function doesn't allocate memory and doesn't fail.
  *
+ *  @param output A buffer where a NULL-terminated string will be placed.
+ *                The string will contain len-1 printable symbols.
  *  @param len Number of bytes reserved for the output string, including
  *             end of line '\0'.
  *
diff --git a/src/resolver.h b/src/resolver.h
index 9f9924d..a690d76 100644
--- a/src/resolver.h
+++ b/src/resolver.h
@@ -36,6 +36,7 @@ typedef struct resolver_srv_rr_struc {
 /** Perform lookup for RFC1035 message format.
  *  This function allocates all elements.
  *
+ *  @param ctx a Strophe context object
  *  @param buf message in RFC1035 format
  *  @param len length of the message
  *  @param srv_rr_list is the result
@@ -46,6 +47,7 @@ int resolver_srv_lookup_buf(xmpp_ctx_t *ctx, const unsigned char *buf,
                             size_t len, resolver_srv_rr_t **srv_rr_list);
 /** Resolve SRV record.
  *
+ *  @param ctx a Strophe context object
  *  @param service service of the SRV record
  *  @param proto protocol of the SRV record
  *  @param domain resolving domain
@@ -59,6 +61,7 @@ int resolver_srv_lookup(xmpp_ctx_t *ctx, const char *service, const char *proto,
 /** Release a list returned by resolver_srv_lookup() or
  *  resolver_srv_lookup_buf().
  *
+ *  @param ctx a Strophe context object
  *  @param srv_rr_list a list allocated by lookup functions
  */
 void resolver_srv_free(xmpp_ctx_t *ctx, resolver_srv_rr_t *srv_rr_list);
diff --git a/src/stanza.c b/src/stanza.c
index 208c0f1..db70bf3 100644
--- a/src/stanza.c
+++ b/src/stanza.c
@@ -1101,6 +1101,7 @@ _stanza_new_with_attrs(xmpp_ctx_t *ctx, const char * const name,
 /** Create a <message/> stanza object with given attributes.
  *  Attributes are optional and may be NULL.
  *
+ *  @param ctx a Strophe context object
  *  @param type attribute 'type'
  *  @param to attribute 'to'
  *  @param id attribute 'id'
@@ -1187,6 +1188,7 @@ int xmpp_message_set_body(xmpp_stanza_t *msg, const char * const text)
 /** Create an <iq/> stanza object with given attributes.
  *  Attributes are optional and may be NULL.
  *
+ *  @param ctx a Strophe context object
  *  @param type attribute 'type'
  *  @param id attribute 'id'
  *
@@ -1201,6 +1203,8 @@ xmpp_stanza_t *xmpp_iq_new(xmpp_ctx_t *ctx, const char * const type,
 }
 
 /** Create a <presence/> stanza object.
+ *
+ *  @param ctx a Strophe context object
  *
  *  @return a new Strophe stanza object
  *
diff --git a/src/uuid.c b/src/uuid.c
index 6a5dc9f..3df1425 100644
--- a/src/uuid.c
+++ b/src/uuid.c
@@ -24,6 +24,7 @@
 
 /** Generate UUID version 4 in pre-allocated buffer.
  *
+ *  @param ctx a Strophe context object
  *  @param uuid pre-allocated buffer of size (XMPP_UUID_LEN + 1)
  */
 static void crypto_uuid_gen(xmpp_ctx_t *ctx, char *uuid)
@@ -56,6 +57,8 @@ static void crypto_uuid_gen(xmpp_ctx_t *ctx, char *uuid)
  *  This function allocates memory for the resulting string and must be freed
  *  with xmpp_free().
  *
+ *  @param ctx a Strophe context object
+ *
  *  @return ASCIIZ string
  */
 char *xmpp_uuid_gen(xmpp_ctx_t *ctx)