fix Doxygen warnings

Signed-off-by: Steffen Jaeckel <jaeckel-floss@eyet-services.de>

Doxyfile

@@ -1831,7 +1831,7 @@ COMPACT_LATEX          = NO
 # The default value is: a4.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
 # that should be included in the LaTeX output. The package can be specified just
@@ -2530,7 +2530,7 @@ INTERACTIVE_SVG        = NO
 # found. If left blank, it is assumed the dot tool can be found in the path.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_PATH               = /Applications/Doxygen.app/Contents/Resources/
+DOT_PATH               =
 
 # The DOTFILE_DIRS tag can be used to specify one or more directories that
 # contain dot files that are included in the documentation (see the \dotfile

src/conn.c

@@ -14,6 +14,9 @@
  */
 
 /** @defgroup Connections Connection management
+ *  These functions manage a connection object.
+ *
+ *  A part of those functions is listed under the \ref TLS section.
  */
 
 #include <errno.h>
@@ -414,7 +417,6 @@ void xmpp_conn_set_jid(xmpp_conn_t *conn, const char *jid)
  *  @param conn a Strophe connection object
  *  @param hndl certfail Handler function
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 void xmpp_conn_set_certfail_handler(xmpp_conn_t *const conn,
@@ -426,9 +428,8 @@ void xmpp_conn_set_certfail_handler(xmpp_conn_t *const conn,
 /** Set the CAfile
  *
  *  @param conn a Strophe connection object
- *  @param cert path to a certificate file
+ *  @param path path to a certificate file
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 void xmpp_conn_set_cafile(xmpp_conn_t *const conn, const char *path)
@@ -439,9 +440,8 @@ void xmpp_conn_set_cafile(xmpp_conn_t *const conn, const char *path)
 /** Set the CApath
  *
  *  @param conn a Strophe connection object
- *  @param cert path to a folder containing certificates
+ *  @param path path to a folder containing certificates
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 void xmpp_conn_set_capath(xmpp_conn_t *const conn, const char *path)
@@ -458,7 +458,6 @@ void xmpp_conn_set_capath(xmpp_conn_t *const conn, const char *path)
  *
  *  @return a Strophe Certificate object
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 xmpp_tlscert_t *xmpp_conn_get_peer_cert(xmpp_conn_t *const conn)
@@ -476,7 +475,6 @@ xmpp_tlscert_t *xmpp_conn_get_peer_cert(xmpp_conn_t *const conn)
  *  @param cert path to a certificate file
  *  @param key path to a private key file
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 void xmpp_conn_set_client_cert(xmpp_conn_t *const conn,
@@ -498,7 +496,6 @@ void xmpp_conn_set_client_cert(xmpp_conn_t *const conn,
  *
  *  @return the number of xmppAddr entries in the client certificate
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 unsigned int xmpp_conn_cert_xmppaddr_num(xmpp_conn_t *const conn)
@@ -513,7 +510,6 @@ unsigned int xmpp_conn_cert_xmppaddr_num(xmpp_conn_t *const conn)
  *
  *  @return a string containing the xmppAddr or NULL if n is out of range
  *
- *  @ingroup Connections
  *  @ingroup TLS
  */
 char *xmpp_conn_cert_xmppaddr(xmpp_conn_t *const conn, unsigned int n)

src/rand.h

@@ -31,6 +31,7 @@ xmpp_rand_t *xmpp_rand_new(xmpp_ctx_t *ctx);
 /** Destroy an xmpp_rand_t object.
  *
  *  @param ctx A Strophe context object
+ *  @param rand A xmpp_rand_t object
  *
  *  @ingroup Random
  */
@@ -46,6 +47,10 @@ int xmpp_rand(xmpp_rand_t *rand);
 /** Generate random bytes.
  *  Generates len bytes and stores them to the output buffer.
  *
+ *  @param rand A xmpp_rand_t object
+ *  @param output A buffer where a len random bytes will be placed.
+ *  @param len Number of bytes reserved for the output..
+ *
  *  @ingroup Random
  */
 void xmpp_rand_bytes(xmpp_rand_t *rand, unsigned char *output, size_t len);
@@ -53,6 +58,7 @@ 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 rand A xmpp_rand_t object
  *  @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

src/stanza.c

@@ -1271,7 +1271,7 @@ copy_error:
  *  Check https://tools.ietf.org/html/rfc6120#section-8.3 for details.
  *
  *  @param stanza a Strophe stanza object
- *  @param error_type type attribute in the <error/> child element
+ *  @param error_type type attribute in the `<error/>` child element
  *  @param condition the defined-condition (e.g. "item-not-found")
  *  @param text optional description, may be NULL
  *
@@ -1386,7 +1386,7 @@ static xmpp_stanza_t *_stanza_new_with_attrs(xmpp_ctx_t *ctx,
     return stanza;
 }
 
-/** Create a <message/> stanza object with given attributes.
+/** Create a `<message/>` stanza object with given attributes.
  *  Attributes are optional and may be NULL.
  *
  *  @param ctx a Strophe context object
@@ -1406,13 +1406,13 @@ xmpp_stanza_t *xmpp_message_new(xmpp_ctx_t *ctx,
     return _stanza_new_with_attrs(ctx, "message", type, id, to);
 }
 
-/** Get text from <body/> child element.
+/** Get text from `<body/>` child element.
  *  This function returns new allocated string. The caller is responsible
  *  for freeing this string with xmpp_free().
  *
- *  @param msg well formed <message/> stanza
+ *  @param msg well formed `<message/>` stanza
  *
- *  @return allocated string or NULL on failure (no <body/> element or
+ *  @return allocated string or NULL on failure (no `<body/>` element or
  *      memory allocation error)
  *
  *  @ingroup Stanza
@@ -1431,9 +1431,10 @@ char *xmpp_message_get_body(xmpp_stanza_t *msg)
     return text;
 }
 
-/** Add <body/> child element to a <message/> stanza with the given text.
+/** Add `<body/>` child element to a `<message/>` stanza with the given text.
  *
- *  @param msg a <message> stanza object without <body/> child element.
+ *  @param msg a `<message>` stanza object without `<body/>` child element.
+ *  @param text The text that shall be placed in the body.
  *
  *  @return 0 on success (XMPP_EOK), and a number less than 0 on failure
  *      (XMPP_EMEM, XMPP_EINVOP)
@@ -1448,7 +1449,7 @@ int xmpp_message_set_body(xmpp_stanza_t *msg, const char *text)
     const char *name;
     int ret;
 
-    /* check that msg is a <message/> stanza and doesn't contain <body/> */
+    /* check that msg is a `<message/>` stanza and doesn't contain `<body/>` */
     name = xmpp_stanza_get_name(msg);
     body = xmpp_stanza_get_child_by_name(msg, "body");
     if (!name || strcmp(name, "message") != 0 || body)
@@ -1475,7 +1476,7 @@ int xmpp_message_set_body(xmpp_stanza_t *msg, const char *text)
     return ret;
 }
 
-/** Create an <iq/> stanza object with given attributes.
+/** Create an `<iq/>` stanza object with given attributes.
  *  Attributes are optional and may be NULL.
  *
  *  @param ctx a Strophe context object
@@ -1491,7 +1492,7 @@ xmpp_stanza_t *xmpp_iq_new(xmpp_ctx_t *ctx, const char *type, const char *id)
     return _stanza_new_with_attrs(ctx, "iq", type, id, NULL);
 }
 
-/** Create a <presence/> stanza object.
+/** Create a `<presence/>` stanza object.
  *
  *  @param ctx a Strophe context object
  *

src/tls.c

@@ -112,7 +112,6 @@ const char *xmpp_tlscert_get_string(const xmpp_tlscert_t *cert,
  *
  *  c.f. \ref xmpp_cert_element_t for details.
  *
- *  @param cert a Strophe TLS certificate object
  *  @param elmnt which element
  *
  *  @return a string with the description