Bug#33734206 doc-comment warning in sql/

Issue
=====

clang -Wdocumentation reports:

  sql/sql_class.cc:3213:4: warning: '@returns' command used in a comment
  that is attached to a function returning void [-Wdocumentation]

Doxygen's param command is spec'ed as:

  @param '['dir']' <parameter-name> { parameter description }

which makes [out] in:

  @param new_item [out]       return new_item, if created

part of the param-description, instead of 'dir'.

Change
======

- @param name [in] -> @param[in] name
- use @returns instead of @RetVal when no value is specified
- removed empty @returns
- @param name [out] -> @param[out] name

RB: 27548

Author: weigon

sql-common/net_serv.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2000, 2021, Oracle and/or its affiliates.
+/* Copyright (c) 2000, 2022, Oracle and/or its affiliates.
 
    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,
@@ -125,10 +125,9 @@ void net_extension_free(NET *net) {
   If the caller is server then fetch is fromthe server extension
   structure.
 
-  @param net  [in]    NET structure
+  @param[in] net    NET structure
 
-  @return
-    @retval  mysql_compress_context structure pointer
+  @returns mysql_compress_context structure pointer
 */
 static mysql_compress_context *compress_context(NET *net) {
   mysql_compress_context *mysql_compress_ctx = nullptr;
@@ -1815,9 +1814,8 @@ static void net_read_init_offsets(NET *net, size_t &start_of_packet,
   @param [in, out]  multi_byte_packet Flag that indicate if packet is multibyte
   @param [in, out]  first_packet_offset Starting offset of the packet to read
 
-  @returns
-   @retval true   The last packet read
-   @retval false  Otherwise
+  @retval true   The last packet read
+  @retval false  Otherwise
 */
 static bool net_read_process_buffer(NET *net, size_t &start_of_packet,
                                     size_t &buf_length, uint &multi_byte_packet,

sql/item_cmpfunc.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2000, 2021, Oracle and/or its affiliates.
+/* Copyright (c) 2000, 2022, Oracle and/or its affiliates.
 
    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,
@@ -5637,7 +5637,7 @@ bool Item_cond::fix_fields(THD *thd, Item **ref) {
 
   @param thd                  Current thread
   @param item                 Item which needs to be evaluated
-  @param new_item [out]       return new_item, if created
+  @param[out] new_item        return new_item, if created
 
   @return               true, if error
                         false, on success

sql/sql_class.cc

@@ -1,5 +1,5 @@
 /*
-   Copyright (c) 2000, 2021, Oracle and/or its affiliates.
+   Copyright (c) 2000, 2022, Oracle and/or its affiliates.
 
    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,
@@ -3200,8 +3200,6 @@ void THD::disable_mem_cnt() {
   @param db         Schema name in which table is being created.
   @param tablename  Table name being created.
   @param hton       Handlerton representing engine used for table.
-
-  @returns void
 */
 void Transactional_ddl_context::init(dd::String_type db,
                                      dd::String_type tablename,
@@ -3215,8 +3213,6 @@ void Transactional_ddl_context::init(dd::String_type db,
 /**
   Remove the table share used while creating the table, if the transaction
   is being rolledback.
-
-  @returns void
 */
 void Transactional_ddl_context::rollback() {
   if (!inited()) return;
@@ -3241,8 +3237,6 @@ void Transactional_ddl_context::rollback() {
   End the transactional context created by calling post ddl hook for engine
   on which table is being created. This is done after transaction rollback
   and commit.
-
-  @returns void
 */
 void Transactional_ddl_context::post_ddl() {
   if (!inited()) return;