Review doxygen warnings

We write doxygen comments but we do not verify them. So
quite some errors have crept in. Trying to reduce them
by reviewing the warnings output of doxygen and addressing
most of them.

Did generally ignore "The following parameter is not documented"
warnings (except those caused by typos). Fixing those will
require more work.

Usual errors fixed:
 - Wrong usage of @file
 - Wrong spellings of @param
 - Desync between function declaration and comment
   (usually param names)

Change-Id: I7a852eb5fafae3a0e85dd89ea6d4c91fcf2fab4e
Signed-off-by: Frank Lichtenheld <[email protected]>
Acked-by: Arne Schwabe <[email protected]>
Message-Id: <[email protected]>
URL: https://www.mail-archive.com/[email protected]/msg30256.html
Signed-off-by: Gert Doering <[email protected]>

doc/doxygen/doc_compression.h

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Compression module documentation file.
+ * @file
+ * Data Channel Compression module documentation file.
  */
 
 /**

doc/doxygen/doc_protocol_overview.h

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Network protocol overview documentation file.
+ * @file
+ * Network protocol overview documentation file.
  */
 
 /**

sample/sample-plugins/simple/base64.c

@@ -44,7 +44,7 @@ plugin_base64_decode_t ovpn_base64_decode = NULL;  /**< Pointer to the openvpn_b
  * returns, any returned pointers are invalid.
  *
  * @param name  String containing the env.var name to search for
- * @param envp  String array pointer to the environment variable
+ * @param envp  String array pointer to the environment variables
  *
  * @return Returns a pointer to the value in the environment variable
  *         table on successful match.  Otherwise NULL is returned
@@ -138,10 +138,11 @@ openvpn_plugin_open_v3(const int v3structver,
  * For the arguments, see the include/openvpn-plugin.h file
  * for details on the function parameters
  *
- * @param args        Pointer to a struct with details about the plug-in
- *                    call from the main OpenVPN process.
- * @param returndata  Pointer to a struct where the plug-in can provide
- *                    information back to OpenVPN to be processed
+ * @param handle   Pointer to the plug-in global context buffer, which
+ *                 need to be released by this function
+ * @param type     Type of the hook
+ * @param argv     String array pointer to arguments for the hook
+ * @param envp     String array pointer to current environment variables
  *
  * @return  Must return OPENVPN_PLUGIN_FUNC_SUCCESS or
  *          OPENVPN_PLUGIN_FUNC_DEFERRED on success.  Otherwise it

src/openvpn/argv.c

@@ -42,7 +42,7 @@
  *  Resizes the list of arguments struct argv can carry.  This resize
  *  operation will only increase the size, never decrease the size.
  *
- *  @param *a      Valid pointer to a struct argv to resize
+ *  @param a       Valid pointer to a struct argv to resize
  *  @param newcap  size_t with the new size of the argument list.
  */
 static void
@@ -66,7 +66,7 @@ argv_extend(struct argv *a, const size_t newcap)
  *  Initialise an already allocated struct argv.
  *  It is expected that the input argument is a valid pointer.
  *
- *  @param *a  Pointer to a struct argv to initialise
+ *  @param a  Pointer to a struct argv to initialise
  */
 static void
 argv_init(struct argv *a)
@@ -96,7 +96,7 @@ argv_new(void)
  *  Frees all memory allocations allocated by the struct argv
  *  related functions.
  *
- *  @param *a  Valid pointer to a struct argv to release memory from
+ *  @param a  Valid pointer to a struct argv to release memory from
  */
 void
 argv_free(struct argv *a)
@@ -108,7 +108,7 @@ argv_free(struct argv *a)
  *  Resets the struct argv to an initial state.  No memory buffers
  *  will be released by this call.
  *
- *  @param *a      Valid pointer to a struct argv to resize
+ *  @param a      Valid pointer to a struct argv to resize
  */
 static void
 argv_reset(struct argv *a)
@@ -133,7 +133,7 @@ argv_reset(struct argv *a)
  *  This approach ensures that the list does grow bulks and only when the
  *  current limit is reached.
  *
- *  @param *a   Valid pointer to the struct argv to extend
+ *  @param a    Valid pointer to the struct argv to extend
  *  @param add  size_t with the number of elements to add.
  *
  */
@@ -150,9 +150,9 @@ argv_grow(struct argv *a, const size_t add)
  *  This will ensure the list size in struct argv has the needed capacity to
  *  store the value.
  *
- *  @param *a    struct argv where to append the new string value
- *  @param *str  Pointer to string to append.  The provided string *MUST* have
- *               been malloc()ed or NULL.
+ *  @param a    struct argv where to append the new string value
+ *  @param str  Pointer to string to append.  The provided string *MUST* have
+ *              been malloc()ed or NULL.
  */
 static void
 argv_append(struct argv *a, char *str)
@@ -167,7 +167,7 @@ argv_append(struct argv *a, char *str)
  *  values being copied from the source input.
  *
  *
- *  @param *source   Valid pointer to the source struct argv to clone.  It may
+ *  @param source    Valid pointer to the source struct argv to clone.  It may
  *                   be NULL.
  *  @param headroom  Number of slots to leave empty in front of the slots
  *                   copied from the source.
@@ -199,8 +199,8 @@ argv_clone(const struct argv *source, const size_t headroom)
 /**
  *  Inserts an argument string in front of all other argument slots.
  *
- *  @param  *a     Valid pointer to the struct argv to insert the argument into
- *  @param  *head  Pointer to the char * string with the argument to insert
+ *  @param  a     Valid pointer to the struct argv to insert the argument into
+ *  @param  head  Pointer to the string with the argument to insert
  *
  *  @returns Returns a new struct argv with the inserted argument in front
  */
@@ -217,8 +217,8 @@ argv_insert_head(const struct argv *a, const char *head)
  *  Generate a single string with all the arguments in a struct argv
  *  concatenated.
  *
- *  @param *a    Valid pointer to the struct argv with the arguments to list
- *  @param *gc   Pointer to a struct gc_arena managed buffer
+ *  @param a     Valid pointer to the struct argv with the arguments to list
+ *  @param gc    Pointer to a struct gc_arena managed buffer
  *  @param flags Flags passed to the print_argv() function.
  *
  *  @returns Returns a string generated by print_argv() with all the arguments
@@ -237,7 +237,7 @@ argv_str(const struct argv *a, struct gc_arena *gc, const unsigned int flags)
  *  Write the arguments stored in a struct argv via the msg() command.
  *
  *  @param msglev  Integer with the message level used by msg().
- *  @param *a      Valid pointer to the struct argv with the arguments to write.
+ *  @param a       Valid pointer to the struct argv with the arguments to write.
  */
 void
 argv_msg(const int msglev, const struct argv *a)
@@ -251,9 +251,9 @@ argv_msg(const int msglev, const struct argv *a)
  *  Similar to argv_msg() but prefixes the messages being written with a
  *  given string.
  *
- *  @param msglev   Integer with the message level used by msg().
- *  @param *a       Valid pointer to the struct argv with the arguments to write
- *  @param *prefix  Valid char * pointer to the prefix string
+ *  @param msglev  Integer with the message level used by msg().
+ *  @param a       Valid pointer to the struct argv with the arguments to write
+ *  @param prefix  Valid pointer to the prefix string
  *
  */
 void
@@ -272,13 +272,13 @@ argv_msg_prefix(const int msglev, const struct argv *a, const char *prefix)
  *  format string, with space replaced by delim and adds the number of
  *  arguments to the count parameter.
  *
- *  @param *format  Pointer to a the format string to process
- *  @param delim    Char with the delimiter to use
- *  @param *count   size_t pointer used to return the number of
- *                  tokens (argument slots) found in the format string.
- *  @param *gc      Pointer to a gc_arena managed buffer.
+ *  @param format  Pointer to a the format string to process
+ *  @param delim   Char with the delimiter to use
+ *  @param count   size_t pointer used to return the number of
+ *                 tokens (argument slots) found in the format string.
+ *  @param gc      Pointer to a gc_arena managed buffer.
  *
- *  @returns Returns a parsed format string (char *), together with the
+ *  @returns Returns a parsed format string, together with the
  *           number of tokens parts found (via *count).  The result string
  *           is allocated within the gc_arena managed buffer.  If the
  *           gc_arena pointer is NULL, the returned string must be explicitly
@@ -332,11 +332,11 @@ argv_prep_format(const char *format, const char delim, size_t *count,
  *  argv_prep_format() before we let libc's printf() do the parsing.
  *  Then split the resulting string at the injected delimiters.
  *
- *  @param *argres  Valid pointer to a struct argv where the resulting parsed
- *                  arguments, based on the format string.
- *  @param *format  Char* string with a printf() compliant format string
- *  @param arglist  A va_list with the arguments to be consumed by the format
- *                  string
+ *  @param argres  Valid pointer to a struct argv where the resulting parsed
+ *                 arguments, based on the format string.
+ *  @param format  Char string with a printf() compliant format string
+ *  @param arglist A va_list with the arguments to be consumed by the format
+ *                 string
  *
  *  @returns Returns true if the parsing and processing was successfully.  If
  *           the resulting number of arguments does not match the expected
@@ -429,8 +429,8 @@ argv_printf_arglist(struct argv *argres, const char *format, va_list arglist)
  *  This will always reset and ensure the result is based on a pristine
  *  struct argv.
  *
- *  @param *argres  Valid pointer to a struct argv where the result will be put.
- *  @param *format  printf() compliant (char *) format string.
+ *  @param argres  Valid pointer to a struct argv where the result will be put.
+ *  @param format  printf() compliant format string.
  *
  *  @returns Returns true if the parsing was successful.  See
  *           argv_printf_arglist() for more details.  The parsed result will
@@ -453,8 +453,8 @@ argv_printf(struct argv *argres, const char *format, ...)
  *  struct argv and populets the argument slots based on the printf() based
  *  format string.
  *
- *  @param *argres  Valid pointer to a struct argv where the result will be put.
- *  @param *format  printf() compliant (char *) format string.
+ *  @param argres  Valid pointer to a struct argv where the result will be put.
+ *  @param format  printf() compliant format string.
  *
  *  @returns Returns true if the parsing was successful.  See
  *           argv_printf_arglist() for more details.  The parsed result will
@@ -474,9 +474,9 @@ argv_printf_cat(struct argv *argres, const char *format, ...)
  *  Parses a command string, tokenizes it and puts each element into a separate
  *  struct argv argument slot.
  *
- *  @params *argres  Valid pointer to a struct argv where the parsed result
- *                   will be found.
- *  @params *cmdstr  Char * based string to parse
+ *  @param argres  Valid pointer to a struct argv where the parsed result
+ *                 will be found.
+ *  @param cmdstr  Char based string to parse
  *
  */
 void

src/openvpn/buffer.h

@@ -1218,7 +1218,7 @@ struct buffer_list *buffer_list_file(const char *fn, int max_line_len);
 /**
  * buffer_read_from_file - copy the content of a file into a buffer
  *
- * @param file      path to the file to read
+ * @param filename  path to the file to read
  * @param gc        the garbage collector to use when allocating the buffer. It
  *                  is passed to alloc_buf_gc() and therefore can be NULL.
  *

src/openvpn/console.h

@@ -112,7 +112,7 @@ query_user_exec(void)
 
 
 /**
- * A plain "make Gert happy" wrapper.  Same arguments as @query_user_add
+ * A plain "make Gert happy" wrapper.  Same arguments as query_user_add()
  *
  * FIXME/TODO: Remove this when refactoring the complete user query process
  *             to be called at start-up initialization of OpenVPN.

src/openvpn/console_builtin.c

@@ -166,7 +166,7 @@ open_tty(const bool write)
 /**
  * Closes the TTY FILE pointer, but only if it is not a stdin/stderr FILE object.
  *
- * @params fp     FILE pointer to close
+ * @param fp     FILE pointer to close
  *
  */
 static void
@@ -184,10 +184,10 @@ close_tty(FILE *fp)
 /**
  *  Core function for getting input from console
  *
- *  @params prompt    The prompt to present to the user
- *  @params echo      Should the user see what is being typed
- *  @params input     Pointer to the buffer used to save the user input
- *  @params capacity  Size of the input buffer
+ *  @param prompt    The prompt to present to the user
+ *  @param echo      Should the user see what is being typed
+ *  @param input     Pointer to the buffer used to save the user input
+ *  @param capacity  Size of the input buffer
  *
  *  @returns Returns True if user input was gathered
  */

src/openvpn/console_systemd.c

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Alternative method to query for user input, using systemd
+ * @file
+ * Alternative method to query for user input, using systemd
  *
  */
 

src/openvpn/crypto.h

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Cryptography Module
+ * @file
+ * Data Channel Cryptography Module
  *
  * @addtogroup data_crypto Data Channel Crypto module
  *
@@ -491,7 +492,7 @@ bool crypto_check_replay(struct crypto_options *opt,
  * this and add it themselves.
  *
  * @param kt            Struct with the crypto algorithm to use
- * @param packet_id_size Size of the packet id
+ * @param pkt_id_size   Size of the packet id
  * @param occ           if true calculates the overhead for crypto in the same
  *                      incorrect way as all previous OpenVPN versions did, to
  *                      end up with identical numbers for OCC compatibility
@@ -509,7 +510,7 @@ unsigned int crypto_max_overhead(void);
  * and write to file.
  *
  * @param filename          Filename of the server key file to create.
- * @param pem_name          The name to use in the PEM header/footer.
+ * @param key_name          The name to use in the PEM header/footer.
  */
 void
 write_pem_key_file(const char *filename, const char *key_name);

src/openvpn/crypto_backend.h

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Cryptography SSL library-specific backend interface
+ * @file
+ * Data Channel Cryptography SSL library-specific backend interface
  */
 
 #ifndef CRYPTO_BACKEND_H_
@@ -339,7 +340,7 @@ void cipher_ctx_free(cipher_ctx_t *ctx);
  *                      \c OPENVPN_OP_ENCRYPT or \c OPENVPN_OP_DECRYPT).
  */
 void cipher_ctx_init(cipher_ctx_t *ctx, const uint8_t *key,
-                     const char *cipername, crypto_operation_t enc);
+                     const char *ciphername, crypto_operation_t enc);
 
 /**
  * Returns the size of the IV used by the cipher, in bytes, or 0 if no IV is
@@ -357,7 +358,7 @@ int cipher_ctx_iv_length(const cipher_ctx_t *ctx);
  *
  * @param ctx           The cipher's context
  * @param tag           The buffer to write computed tag in.
- * @param tag_size      The tag buffer size, in bytes.
+ * @param tag_len       The tag buffer size, in bytes.
  */
 int cipher_ctx_get_tag(cipher_ctx_t *ctx, uint8_t *tag, int tag_len);
 

src/openvpn/crypto_mbedtls.c

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Cryptography mbed TLS-specific backend interface
+ * @file
+ * Data Channel Cryptography mbed TLS-specific backend interface
  */
 
 #ifdef HAVE_CONFIG_H

src/openvpn/crypto_mbedtls.h

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Cryptography mbed TLS-specific backend interface
+ * @file
+ * Data Channel Cryptography mbed TLS-specific backend interface
  */
 
 #ifndef CRYPTO_MBEDTLS_H_

src/openvpn/crypto_openssl.c

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Cryptography OpenSSL-specific backend interface
+ * @file
+ * Data Channel Cryptography OpenSSL-specific backend interface
  */
 
 #ifdef HAVE_CONFIG_H

src/openvpn/crypto_openssl.h

@@ -23,7 +23,8 @@
  */
 
 /**
- * @file Data Channel Cryptography OpenSSL-specific backend interface
+ * @file
+ * Data Channel Cryptography OpenSSL-specific backend interface
  */
 
 #ifndef CRYPTO_OPENSSL_H_
@@ -110,8 +111,7 @@ void crypto_print_openssl_errors(const unsigned int flags);
  * This is just a convenience wrapper for often occurring situations.
  *
  * @param flags         Flags to indicate error type and priority.
- * @param format        Format string to print.
- * @param format args   (optional) arguments for the format string.
+ * @param ...           Format string and optional format arguments
  */
 #define crypto_msg(flags, ...) \
     do { \

src/openvpn/dns.c

@@ -34,7 +34,7 @@
  * Parses a string as port and stores it
  *
  * @param   port        Pointer to in_port_t where the port value is stored
- * @param   addr        Port number as string
+ * @param   port_str    Port number as string
  * @return              True if parsing was successful
  */
 static bool