Bug#30956093 documentation warnings reported by clang [1/14]

Problem
-------

building clang and CMAKE_CXX_FLAGS="-Wdocumentation" reports warnings like:

1. empty paragraph passed to '@return' command
2. '@return' command used in a comment that is attached to a function returning void
3. '@param' command used in a comment that is not attached to a function declaration
4. //<! not a Doxygen trailing comment
5. warning: HTML tag 'table' requires an end tag
6. unrecognized parameter passing direction, valid directions are '[in]', '[out]' and '[in,out]'
7. '@interface' command should not be used in a comment attached to a non-interface declaration
8. '@c' command does not have a valid word argument

Change
------

- removed empty @return and @returns from doc-comments
- removed @return on 'return-void' functions
- moved doc-comment in front of functions or typedefs
- fixed trailing comments
- wrap code in \code and \encode to avoid HTML escapes
- replaced [inout] by [in,out]
- removed '@interface' and rely on doxygen's autolink generation
- replaced @RetVal with @returns if the first words isn't a value

RB: 23952

Author: weigon

Diff for: client/dump/sql_formatter.cc

@@ -1,5 +1,5 @@
 /*
-  Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
+  Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License, version 2.0,
@@ -430,11 +430,10 @@ void Sql_formatter::format_sql_objects_definer(
 /**
   Check if the table is innodb stats table in mysql database.
 
-   @param [in] db           Database name
-   @param [in] table        Table name
+  @param [in] db           Database name
+  @param [in] table        Table name
 
-  @return
-    @retval true if it is innodb stats table else false
+  @retval true if it is innodb stats table else false
 */
 bool Sql_formatter::innodb_stats_tables(std::string db, std::string table) {
   return ((db == "mysql") &&

Diff for: client/mysqlbinlog.cc

@@ -1,5 +1,5 @@
 /*
-   Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+   Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2.0,
@@ -1303,7 +1303,7 @@ static bool shall_skip_gtids(const Log_event *ev) {
   - At the end of mysqlbinlog, just after printing all log files(binlog or
     relaylog).
 
-  @param[in|out] print_event_info Context state determining how to print.
+  @param[in,out] print_event_info Context state determining how to print.
 */
 void end_binlog(PRINT_EVENT_INFO *print_event_info) {
   if (in_transaction) {

Diff for: client/mysqldump.cc

@@ -2053,8 +2053,7 @@ static void print_comment(FILE *sql_file, bool is_error, const char *format,
   @param[in]  object_name   object name list (concatenated string)
   @param[out] freemem       should buffer be released after usage
 
-  @return
-    @retval                 pointer to a string with prefixed objects
+  @returns                  pointer to a string with prefixed objects
 */
 static char const *fix_identifier_with_newline(char const *object_name,
                                                bool *freemem) {
@@ -2534,11 +2533,10 @@ static inline bool replication_metadata_tables(const char *db,
 /**
   Check if the table is innodb stats table in mysql database.
 
-   @param [in] db           Database name
-   @param [in] table        Table name
+  @param [in] db           Database name
+  @param [in] table        Table name
 
-  @return
-    @retval true if it is innodb stats table else false
+  @retval true if it is innodb stats table else false
 */
 static inline bool innodb_stats_tables(const char *db, const char *table) {
   return (!my_strcasecmp(charset_info, db, "mysql")) &&
@@ -2552,11 +2550,10 @@ static inline bool innodb_stats_tables(const char *db, const char *table) {
   Check if the command line option includes innodb stats table
   or in any way mysql database.
 
-   @param [in] argc         Total count of positional arguments
-   @param [in] argv         Pointer to positional arguments
+  @param [in] argc         Total count of positional arguments
+  @param [in] argv         Pointer to positional arguments
 
-  @return
-    @retval true if dump contains innodb stats table or else false
+  @retval true if dump contains innodb stats table or else false
 */
 static inline bool is_innodb_stats_tables_included(int argc, char **argv) {
   if (opt_alldbs) return true;

Diff for: components/audit_api_message_emit/audit_api_message_emit.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License, version 2.0,
@@ -191,9 +191,8 @@ char *collation_name = const_cast<char *>(collation);
   @param [in, out]  args      UDF arguments structure
   @param [out]      handler   Error handler
 
-  @return
-    @retval false Set the charset of all arguments successully
-    @retval true  Otherwise
+  @retval false Set the charset of all arguments successully
+  @retval true  Otherwise
 */
 static bool set_args_charset_info(UDF_ARGS *args, IError_handler &handler) {
   for (size_t index = 0; index < args->arg_count; ++index) {
@@ -213,9 +212,8 @@ static bool set_args_charset_info(UDF_ARGS *args, IError_handler &handler) {
   @param [in, out]  initid    A pointer to the UDF_INIT structure
   @param [out]      handler   Error handler that keeps the error message
 
-  @return
-    @retval false Charset info of return value set successfully.
-    @retval true  Otherwise
+  @retval false Charset info of return value set successfully.
+  @retval true  Otherwise
 */
 bool set_return_value_charset_info(UDF_INIT *initid, IError_handler &handler) {
   if (mysql_service_mysql_udf_metadata->result_set(
@@ -240,7 +238,6 @@ bool set_return_value_charset_info(UDF_INIT *initid, IError_handler &handler) {
                           set to false, if the provided argument count is
                           greater, this does not return error.
 
-  @return
   @retval -1  None of the argument definition was matched.
   @retval >=0 n-th argument definition was matched.
 */
@@ -328,7 +325,6 @@ static int arg_check(IError_handler &handler, unsigned int arg_count,
   @param handler Error handler used for error handling.
   @param args    UDF_ARGS structure.
 
-  @return
   @retval false Succeeded. Arguments are ok.
   @retval true  Failed. Error is reported via specified handler.
 */

Diff for: components/mysqlbackup/backup_page_tracker.cc

@@ -57,8 +57,6 @@ bool Backup_page_tracker::backup_id_update() {
 
 /**
    Make a list of the UDFs exposed by mysqlbackup page_tracking.
-
-   @return None
 */
 void Backup_page_tracker::initialize_udf_list() {
   m_udf_list.push_back(new udf_data_t(
@@ -165,8 +163,6 @@ bool Backup_page_tracker::set_page_tracking_init(UDF_INIT *, UDF_ARGS *,
 
 /**
    Callback method for initialization of UDF "mysqlbackup_page_track_set".
-
-   @return None
 */
 void Backup_page_tracker::set_page_tracking_deinit(
     UDF_INIT *initid MY_ATTRIBUTE((unused))) {}
@@ -220,8 +216,6 @@ bool Backup_page_tracker::page_track_get_start_lsn_init(UDF_INIT *, UDF_ARGS *,
 /**
    Callback method for initialization of UDF
    "mysqlbackup_page_track_get_start_lsn"
-
-   @return None
 */
 void Backup_page_tracker::page_track_get_start_lsn_deinit(
     UDF_INIT *initid MY_ATTRIBUTE((unused))) {}
@@ -266,8 +260,6 @@ bool Backup_page_tracker::page_track_get_changed_page_count_init(UDF_INIT *,
 /**
    Callback method for initialization of UDF
    "mysqlbackup_page_track_get_changed_page_count".
-
-   @return None
 */
 void Backup_page_tracker::page_track_get_changed_page_count_deinit(
     UDF_INIT *initid MY_ATTRIBUTE((unused))) {}
@@ -319,8 +311,6 @@ bool Backup_page_tracker::page_track_get_changed_pages_init(UDF_INIT *,
 /**
    Callback method for initialization of UDF
    "mysqlbackup_page_track_get_changed_pages".
-
-   @return None
 */
 void Backup_page_tracker::page_track_get_changed_pages_deinit(
     UDF_INIT *initid MY_ATTRIBUTE((unused))) {

Diff for: components/test/perfschema/test_pfs_resource_group.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2.0,
@@ -140,7 +140,6 @@ void session_disconnect_callback(const PSI_thread_attrs *thread_attrs) {
 /**
   Test the Resource Group service.
   Log messages are written to the console and log file.
-  @return NULL for success
 */
 void session_event(const Event_info &event) {
   PSI_thread_attrs attrs = event.m_attrs;

Diff for: components/test/test_audit_api_message.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2019, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License, version 2.0,
@@ -51,7 +51,6 @@ REQUIRES_SERVICE_PLACEHOLDER(mysql_audit_api_message);
   @param null_value Unused.
   @param error      Unused.
 
-  @return
   @retval 0 This function always returns 0.
 */
 static long long message_internal(UDF_INIT *init MY_ATTRIBUTE((unused)),
@@ -82,7 +81,6 @@ static long long message_internal(UDF_INIT *init MY_ATTRIBUTE((unused)),
   @param null_value Unused.
   @param error      Unused.
 
-  @return
   @retval 0 This function always returns 0.
 */
 static long long message_user(UDF_INIT *init MY_ATTRIBUTE((unused)),