enabled and mitigated -Wdocumentation and `-Wdocumentation-unknown-…

…command` Clang compiler warnings

common/list.h

@@ -104,7 +104,6 @@ list_dump_items(struct list *self);
  *
  * @param str String to split.
  * @param character Character used as the delimiter between strings.
- * @param start_index Index to start on the source list (zero based)
  *
  * @result 0 if a memory allocation failure occurred.
  *

common/log.c

@@ -84,7 +84,7 @@ internal_log_file_open(const char *fname)
 /**
  *
  * @brief Converts xrdp log level to syslog logging level
- * @param xrdp logging level
+ * @param lvl logging level
  * @return syslog equivalent logging level
  *
  */
@@ -114,7 +114,6 @@ internal_log_xrdp2syslog(const enum logLevels lvl)
  * @brief Converts xrdp log levels to textual logging levels
  * @param lvl logging level
  * @param str pointer to a string, must be allocated before
- * @return The log string in str pointer.
  *
  */
 void
@@ -232,8 +231,6 @@ internal_log_end(struct log_config *l_cfg)
 
 /**
  * Converts a string representing the log level to a value
- * @param buf
- * @return
  */
 enum logLevels
 internal_log_text2level(const char *buf)
@@ -828,8 +825,7 @@ log_start_from_param(const struct log_config *src_log_config)
 /**
  * This function initialize the log facilities according to the configuration
  * file, that is described by the in parameter.
- * @param iniFile
- * @param applicationName, the name that is used in the log for the running application
+ * @param applicationName the name that is used in the log for the running application
  * @return 0 on success
  */
 enum logReturns
@@ -873,7 +869,6 @@ log_start(const char *iniFile, const char *applicationName,
 
 /**
  * Function that terminates all logging
- * @return
  */
 enum logReturns
 log_end(void)
@@ -1121,7 +1116,6 @@ internal_log_message(const enum logLevels lvl,
 
 /**
  * Return the configured log file name
- * @return
  */
 char *
 getLogFile(char *replybuf, int bufsize)
@@ -1147,7 +1141,6 @@ getLogFile(char *replybuf, int bufsize)
 
 /**
  * Returns formatted datetime for log
- * @return
  */
 char *
 getFormattedDateTime(char *replybuf, int bufsize)

common/log.h

@@ -224,7 +224,6 @@ struct log_config
  *
  * @brief Starts the logging subsystem
  * @param l_cfg logging system configuration
- * @return
  *
  */
 enum logReturns
@@ -241,7 +240,7 @@ internal_log_end(struct log_config *l_cfg);
 
 /**
  * Converts a log level to a string
- * @param lvl, the loglevel
+ * @param lvl the loglevel
  * @param str pointer where the string will be stored.
  */
 void
@@ -250,7 +249,7 @@ internal_log_lvl2str(const enum logLevels lvl, char *str);
 /**
  *
  * @brief Converts a string to a log level
- * @param s The string to convert
+ * @param buf The string to convert
  * @return The corresponding level or LOG_LEVEL_DEBUG if error
  *
  */
@@ -273,12 +272,11 @@ internal_log_config_dump(struct log_config *config);
 
 /**
  * the log function that all files use to log an event.
- * @param lvl, the loglevel
- * @param override_destination_level, if true then the destination log level is not used
- * @param override_log_level, the loglevel instead of the destination log level if override_destination_level is true
- * @param msg, the logtext.
- * @param ap, the values for the message format arguments
- * @return
+ * @param lvl the loglevel
+ * @param override_destination_level if true then the destination log level is not used
+ * @param override_log_level the loglevel instead of the destination log level if override_destination_level is true
+ * @param msg the logtext.
+ * @param ap the values for the message format arguments
  */
 enum logReturns
 internal_log_message(const enum logLevels lvl,
@@ -288,9 +286,9 @@ internal_log_message(const enum logLevels lvl,
                      va_list ap);
 
 /**
- * @param log_level, the log level
- * @param override_destination_level, if true then the destination log level is ignored.
- * @param override_log_level, the log level to use instead of the destination log level
+ * @param log_level the log level
+ * @param override_destination_level if true then the destination log level is ignored.
+ * @param override_log_level the log level to use instead of the destination log level
  *      if override_destination_level is true
  * @return true if at least one log destination will accept a message logged at the given level.
  */
@@ -300,9 +298,9 @@ internal_log_is_enabled_for_level(const enum logLevels log_level,
                                   const enum logLevels override_log_level);
 
 /**
- * @param function_name, the function name (typically the __func__ macro)
- * @param file_name, the file name (typically the __FILE__ macro)
- * @param[out] log_level_return, the log level to use instead of the destination log level
+ * @param function_name the function name (typically the __func__ macro)
+ * @param file_name the file name (typically the __FILE__ macro)
+ * @param[out] log_level_return the log level to use instead of the destination log level
  * @return true if the logger location overrides the destination log levels
  */
 bool_t
@@ -316,7 +314,6 @@ internal_log_location_overrides_level(const char *function_name,
 /**
  * This function initialize the log facilities according to the configuration
  * file, that is described by the in parameter.
- * @param iniFile
  * @param applicationName the name that is used in the log for the running
  *                        application
  * @param flags Flags to affect the operation of the call
@@ -328,8 +325,6 @@ log_start(const char *iniFile, const char *applicationName,
 
 /**
  * An alternative log_start where the caller gives the params directly.
- * @param config
- * @return
  *
  * @post to avoid memory leaks, the config argument must be free'ed using
  * `log_config_free()`
@@ -344,8 +339,8 @@ log_start_from_param(const struct log_config *src_log_config);
  * The config can be customised by the caller before calling
  * log_start_from_param()
  *
- * @param Default log level
- * @param Log level name, or NULL. This can be used to provide an
+ * @param lvl log level
+ * @param override_name level name, or NULL. This can be used to provide an
  *        override to the default log level, by environment variable or
  *        argument.
  *
@@ -357,10 +352,8 @@ log_config_init_for_console(enum logLevels lvl, const char *override_name);
 /**
  * Read configuration from a file and store the values in the returned
  * log_config.
- * @param file
- * @param applicationName, the application name used in the log events.
- * @param section_prefix, prefix for the logging sections to parse
- * @return
+ * @param applicationName the application name used in the log events.
+ * @param section_prefix prefix for the logging sections to parse
  */
 struct log_config *
 log_config_init_from_config(const char *iniFilename,
@@ -375,7 +368,6 @@ log_config_free(struct log_config *config);
 
 /**
  * Function that terminates all logging
- * @return
  */
 enum logReturns
 log_end(void);
@@ -385,10 +377,8 @@ log_end(void);
  *
  * Please prefer to use the LOG and LOG_DEVEL macros instead of this function directly.
  *
- * @param lvl, the loglevel
- * @param msg, the logtext.
- * @param ...
- * @return
+ * @param lvl the loglevel
+ * @param msg the logtext.
  */
 enum logReturns
 log_message(const enum logLevels lvl, const char *msg, ...) printflike(2, 3);
@@ -405,13 +395,11 @@ log_hexdump(const enum logLevels log_level,
  *
  * Please prefer to use the LOG and LOG_DEVEL macros instead of this function directly.
  *
- * @param function_name, the function name (typically the __func__ macro)
- * @param file_name, the file name (typically the __FILE__ macro)
- * @param line_number, the line number in the file (typically the __LINE__ macro)
- * @param lvl, the loglevel
- * @param msg, the logtext.
- * @param ...
- * @return
+ * @param function_name the function name (typically the __func__ macro)
+ * @param file_name the file name (typically the __FILE__ macro)
+ * @param line_number the line number in the file (typically the __LINE__ macro)
+ * @param lvl the loglevel
+ * @param msg the logtext.
  */
 enum logReturns
 log_message_with_location(const char *function_name,
@@ -434,13 +422,11 @@ log_hexdump_with_location(const char *function_name,
  * This function returns the configured file name for the logfile
  * @param replybuf the buffer where the reply is stored
  * @param bufsize how big is the reply buffer.
- * @return
  */
 char *getLogFile(char *replybuf, int bufsize);
 
 /**
  * Returns formatted datetime for log
- * @return
  */
 char *getFormattedDateTime(char *replybuf, int bufsize);
 

common/os_calls.h

@@ -152,7 +152,7 @@ int      g_sck_select(int sck1, int sck2);
  * @param sck File descriptor for peer
  * @param ip buffer to write IP address to
  * @param bytes Size of ip buffer. Should be at least MAX_IP_ADDRSTRLEN
- * @param[out] portptr Optional variable to receive the port number
+ * @param[out] port Optional variable to receive the port number
  * @return Pointer to IP for convenience
  *
  * If the peer has no IP address (for example, it is a Unix Domain Socket),
@@ -203,7 +203,7 @@ int      g_delete_wait_obj(tintptr obj);
  * @param read_objs Array of read objects
  * @param rcount Number of elements in read_objs
  * @param write_objs Array of write objects
- * @param rcount Number of elements in write_objs
+ * @param wcount Number of elements in write_objs
  * @param mstimeout Timeout in milliseconds. <= 0 means an infinite timeout.
  *
  * @return 0 for success. The objects will need to be polled to

common/string_calls.h

@@ -183,7 +183,7 @@ g_bytes_to_hexdump(const char *src, int len);
 /**
  * Extracts the display number from an X11 display string
  *
- * @param Display string (i.e. g_getenv("DISPLAY"))
+ * @param display_text Display string (i.e. g_getenv("DISPLAY"))
  *
  * @result <0 if the string could not be parsed, or >=0 for a display number
  */
@@ -261,7 +261,6 @@ g_bitmask_to_charstr(int bitmask, const struct bitmask_char bitdefs[],
  *
  * @param str Input string
  * @param bitdefs Array mapping tokens to bitmask values
- * @param delim Delimiter for tokens in str
  * @param[out] unrecognised Buffer for any unrecognised tokens
  * @param unrecognised_len Length of unrecognised including '\0';
  * @return bitmask value for recognised tokens

configure.ac

@@ -205,6 +205,7 @@ AX_GCC_FUNC_ATTRIBUTE([format])
 AX_TYPE_SOCKLEN_T
 AX_CFLAGS_WARN_ALL
 AX_APPEND_COMPILE_FLAGS([-Wwrite-strings])
+AX_APPEND_COMPILE_FLAGS([-Wdocumentation -Wdocumentation-unknown-command])
 
 AM_COND_IF([LINUX],
   [AX_APPEND_COMPILE_FLAGS([-Werror])]) # bsd has warnings that have not been fixed yet

fontutils/dumpfv1.c

@@ -57,7 +57,7 @@ struct program_args
  * Parses the program args
  *
  * @param argc Passed to main
- * @param @argv Passed to main
+ * @param argv Passed to main
  * @param pa program_pargs structure for resulting values
  * @return !=0 for success
  */

libipm/libipm.h

@@ -154,7 +154,7 @@ libipm_msg_out_init(struct trans *trans, unsigned short msgno,
  *
  * @param trans libipm transport
  * @param format a description of any arguments to add to the buffer.
- * @param != 0 if an error occurs
+ * @return != 0 if an error occurs
  *
  * The format string is followed immediately by the arguments it
  * describes. The format string may contain these characters (from the
@@ -299,7 +299,7 @@ libipm_msg_in_peek_type(struct trans *trans);
  *
  * @param trans libipm transport
  * @param format a description of the arguments to read from the buffer.
- * @param != 0 if an error occurs
+ * @return != 0 if an error occurs
  *
  * The format string is followed immediately by the arguments it
  * describes. The format string may contain these characters (from the

libipm/libipm_send.c

@@ -471,7 +471,6 @@ libipm_msg_out_appendv(struct trans *trans, const char *format, va_list *argptr)
  * Prepare the transport to build an output message
  * @param trans libipm trans
  * @param msgno Number of message
- * @return != 0 for error
  */
 static void
 init_output_buffer(struct trans *trans, unsigned short msgno)

libipm/scp_application_types.h

@@ -65,7 +65,7 @@ struct scp_session_info
 enum scp_login_status
 {
     E_SCP_LOGIN_OK = 0, ///< The connection is now loggned in
-    E_SCP_LOGIN_ALREADY_LOGGED_IN, //< A user is currently logged in
+    E_SCP_LOGIN_ALREADY_LOGGED_IN, ///< A user is currently logged in
     E_SCP_LOGIN_NO_MEMORY, ///< Memory allocation failure
     /**
      * User couldn't be authenticated, or user doesn't exist */

libxrdp/xrdp_iso.c

@@ -258,7 +258,6 @@ xrdp_iso_process_rdp_neg_req(struct xrdp_iso *self, struct stream *s)
  * On exit, the TPKT header and the fixed part of the PDU header will have been
  * removed from the stream.
  *
- * @param self
  * @param s [in]
  * @param code [out]
  * @param len [out]

libxrdp/xrdp_mcs.c

@@ -253,7 +253,6 @@ xrdp_mcs_recv(struct xrdp_mcs *self, struct stream *s, int *chan)
  * Parse the identifier and length of a [ITU-T X.690] BER (Basic Encoding Rules)
  * structure header.
  *
- * @param self
  * @param s [in] - the stream to read from
  * @param tag_val [in] - the expected tag value
  * @param len [out] - the length of the structure
@@ -1488,7 +1487,6 @@ xrdp_mcs_send(struct xrdp_mcs *self, struct stream *s, int chan)
 
 /**
  * Internal help function to close the socket
- * @param self
  */
 void
 close_rdp_socket(struct xrdp_mcs *self)

libxrdp/xrdp_rdp.c

@@ -1590,7 +1590,6 @@ xrdp_rdp_send_deactivate(struct xrdp_rdp *self)
 /*****************************************************************************/
 /** Send a [MS-RDPBCGR] TS_SAVE_SESSION_INFO_PDU_DATA message.
  *
- * @param self
  * @param data the data to send to the client in the
  *      TS_SAVE_SESSION_INFO_PDU_DATA message. The first 4 bytes of the data
  *      buffer MUST by the infoType value as specified in MS-RDPBCGR 2.2.10.1.1

sesman/chansrv/chansrv_config.c

@@ -77,8 +77,8 @@ log_to_stdout(const enum logLevels lvl, const char *msg, ...)
  *
  * @param logmsg Function to use to log messages
  * @param names List of definitions in the section
- * @params values List of corresponding values for the names
- * @params cfg Pointer to structure we're filling in
+ * @param values List of corresponding values for the names
+ * @param cfg Pointer to structure we're filling in
  *
  * @return 0 for success
  */
@@ -130,8 +130,8 @@ read_config_security(log_func_t logmsg,
  *
  * @param logmsg Function to use to log messages
  * @param names List of definitions in the section
- * @params values List of corresponding values for the names
- * @params cfg Pointer to structure we're filling in
+ * @param values List of corresponding values for the names
+ * @param cfg Pointer to structure we're filling in
  *
  * @return 0 for success
  */

sesman/chansrv/chansrv_config.h

@@ -65,7 +65,7 @@ config_read(int use_logger, const char *sesman_ini);
 /**
  *
  * @brief Dumps configuration to stdout
- * @param pointer to a config_chansrv struct
+ * @param config pointer to a config_chansrv struct
  *
  */
 void
@@ -74,7 +74,7 @@ config_dump(struct config_chansrv *config);
 /**
  *
  * @brief Frees configuration allocated by config_read()
- * @param pointer to a config_chansrv struct (may be NULL)
+ * @param cs pointer to a config_chansrv struct (may be NULL)
  *
  */
 void