Bug#31037561 enable doc-comment warnings for storage/innobase/

- enabled doc-comment warnings for subdirs depending on
  storage/innobase/
- removed @param that refer to non-existent arguments
- added unused, but documented parameters as [[maybe_unused]]
- fixed one-line doc-comments
- removed @return for functions that return void.
- fixed unintended HTML uses in doc-comments
- added descriptions for @RetVal
- conditional doc-comment if UNIV_HOTBACKUP is defined

Change-Id: I12f8cb1cff4cdbd815dc62146bd350b49c18d27c

Author: weigon

storage/innobase/CMakeLists.txt

@@ -25,8 +25,10 @@
 INCLUDE(innodb.cmake)
 
 MSVC_CPPCHECK_DISABLE()
-# TODO: remove when all -Wdocumentation warnings are fixed.
-DISABLE_DOCUMENTATION_WARNINGS()
+IF(NOT WITH_DEBUG)
+  # the innodb parts are documented assuming WITH_DEBUG (UNIV_DEBUG)
+  DISABLE_DOCUMENTATION_WARNINGS()
+ENDIF()
 
 ADD_DEFINITIONS(-DLOG_SUBSYSTEM_TAG="InnoDB")
 

storage/innobase/buf/buf0flu.cc

@@ -3123,8 +3123,7 @@ void buf_flush_page_cleaner_disabled_debug_update(THD *, SYS_VAR *, void *,
 #endif /* UNIV_DEBUG */
 
 /** Thread tasked with flushing dirty pages from the buffer pools.
-As of now we'll have only one coordinator.
-@param[in]      n_page_cleaners Number of page cleaner threads to create */
+As of now we'll have only one coordinator. */
 static void buf_flush_page_coordinator_thread() {
   auto loop_start_time = std::chrono::steady_clock::now();
   ulint n_flushed = 0;

storage/innobase/dict/dict0dd.cc

@@ -239,12 +239,6 @@ static bool dd_index_match(const dict_index_t *index, const Index *dd_index) {
   return match;
 }
 
-/** Check if the InnoDB table is consistent with dd::Table
-@tparam         Table           dd::Table or dd::Partition
-@param[in]      table                   InnoDB table
-@param[in]      dd_table                dd::Table or dd::Partition
-@return true    if match
-@retval false   if not match */
 template <typename Table>
 bool dd_table_match(const dict_table_t *table, const Table *dd_table) {
   /* Temporary table has no metadata written */

storage/innobase/dict/dict0sdi.cc

@@ -164,7 +164,7 @@ when SDI is corrupted.
 @param[in,out]  tablespace      tablespace object
 @retval         false           success
 @retval         true            failure */
-bool dict_sdi_drop(dd::Tablespace *) {
+bool dict_sdi_drop(dd::Tablespace *tablespace [[maybe_unused]]) {
 #if 0  /* TODO: Enable in WL#9761 */
         uint32  space_id;
         if (dict_sdi_exists(tablespace, &space_id)

storage/innobase/handler/ha_innopart.cc

@@ -777,7 +777,9 @@ inline int ha_innopart::initialize_auto_increment(bool) {
 @param[in]      table_def       dd::Table describing table to be opened
 @retval 1 if error
 @retval 0 if success */
-int ha_innopart::open(const char *name, int, uint, const dd::Table *table_def) {
+int ha_innopart::open(const char *name, int mode [[maybe_unused]],
+                      uint test_if_locked [[maybe_unused]],
+                      const dd::Table *table_def) {
   dict_table_t *ib_table;
   char norm_name[FN_REFLEN];
   THD *thd;

storage/innobase/handler/handler0alter.cc

@@ -846,9 +846,9 @@ static inline Instant_Type innobase_support_instant(
     COLUMN_RENAME_ONLY,           /*!< Only column RENAME */
     VIRTUAL_ADD_DROP_ONLY,        /*!< Only virtual column ADD AND DROP */
     VIRTUAL_ADD_DROP_WITH_RENAME, /*!< Virtual column ADD/DROP with RENAME */
-    INSTANT_ADD,  /*< INSTANT ADD possibly with virtual column ADD and
+    INSTANT_ADD,  /*!< INSTANT ADD possibly with virtual column ADD and
                      column RENAME */
-    INSTANT_DROP, /*|< INSTANT DROP possibly with virtual column ADD/DROP and
+    INSTANT_DROP, /*!< INSTANT DROP possibly with virtual column ADD/DROP and
                     column RENAME */
     NONE
   };
@@ -3578,7 +3578,7 @@ PK columns follows rule(2);
 @param[in]      old_clust_index index to be compared
 @param[in]      new_clust_index index to be compared
 @retval true if both indexes have same order.
-@retval false. */
+@retval false . */
 [[nodiscard]] static bool innobase_pk_order_preserved(
     const ulint *col_map, const dict_index_t *old_clust_index,
     const dict_index_t *new_clust_index) {

storage/innobase/handler/p_s.cc

@@ -432,7 +432,6 @@ void Innodb_data_lock_inspector::destroy_data_lock_wait_iterator(
 @param[in]  id_str           The identifier string
 @param[out] cached_id        The cached identifier string
 @param[out] cached_id_length The cached identifier string length
-@returns string allocated in the performance schema container.
 */
 void alloc_identifier(PSI_server_data_lock_container *container,
                       PSI_identifier kind, const std::string &id_str,

storage/innobase/include/arch0arch.h

@@ -697,7 +697,7 @@ class Arch_File_Ctx {
   @return true if both sets of information are the same
   @param[in]    group   group whose file is being validated
   @param[in]    file_index      index of the file which is being validated
-  @param[in]    start_lsn
+  @param[in]    start_lsn start LSN
   @param[in,out]        reset_count     count of files which has been validated
   @return true if both the sets of information are the same. */
   bool validate(Arch_Group *group, uint file_index, lsn_t start_lsn,

storage/innobase/include/row0pread-adapter.h

@@ -65,7 +65,7 @@ class Parallel_reader_adapter {
   @param[in]  trx               Transaction used for parallel read.
   @param[in]  config            (Cluster) Index scan configuration.
   @param[in]  f                 Callback function.
-  @retval error. */
+  @returns error. */
   [[nodiscard]] dberr_t add_scan(trx_t *trx,
                                  const Parallel_reader::Config &config,
                                  Parallel_reader::F &&f);

storage/innobase/include/ut0rnd.h

@@ -127,7 +127,7 @@ extern thread_local uint64_t random_seed;
 
 /** A helper method, it is used by hash_binary_ib for backward compatibility.
 NOTE: Do not use this method, it produces results that are not hashed well.
-Especially for sequences of pairs of <i+n, j+n> over n. */
+Especially for sequences of pairs of \<i+n, j+n\> over n. */
 constexpr uint32_t hash_uint32_pair_ib(uint32_t n1, uint32_t n2) {
   constexpr uint32_t HASH_RANDOM_MASK = 1463735687;
   constexpr uint32_t HASH_RANDOM_MASK2 = 1653893711;

storage/innobase/log/log0files_governor.cc

@@ -574,7 +574,7 @@ log.writer_mutex acquired iff has_writer_mutex is true.
 @param[in,out]  log               redo log
 @param[in]      has_writer_mutex  true iff this thread has log.writer_mutex
                                   acquired
-@return @see Log_files_governor_iteration_result */
+@return @ref Log_files_governor_iteration_result */
 static Log_files_governor_iteration_result log_files_governor_iteration_low(
     log_t &log, bool has_writer_mutex);
 

storage/innobase/log/log0recv.cc

@@ -2529,13 +2529,21 @@ bool recv_page_is_brand_new(buf_block_t *block) {
   return false;
 }
 
+#ifndef UNIV_HOTBACKUP
 /** Applies the hashed log records to the page, if the page lsn is less than
 the lsn of a log record. This can be called when a buffer page has just been
 read in, or also for a page already in the buffer pool.
 
 @param[in]      just_read_in    true if the IO handler calls this for a freshly
                                 read page
 @param[in,out]  block           buffer block */
+#else
+/** Applies the hashed log records to the page, if the page lsn is less than
+the lsn of a log record. This can be called when a buffer page has just been
+read in, or also for a page already in the buffer pool.
+
+@param[in,out]  block           buffer block */
+#endif
 void recv_recover_page_func(
 #ifndef UNIV_HOTBACKUP
     bool just_read_in,

storage/innobase/os/os0file.cc

@@ -3752,8 +3752,6 @@ ssize_t SyncFileIO::execute(const IORequest &request) {
 
 /** Free storage space associated with a section of the file.
 @param[in]      fh              Open file handle
-@param[in]      page_size       Tablespace page size
-@param[in]      block_size      File system block size
 @param[in]      off             Starting offset (SEEK_SET)
 @param[in]      len             Size of the hole
 @return 0 on success or errno */

storage/innobase/row/row0ins.cc

@@ -2279,8 +2279,8 @@ of a clustered index entry.
 @param[in]      thd     client connection, or NULL
 @param[in]      index   clustered index
 @return error code
-@retval DB_SUCCESS
-@retval DB_OUT_OF_FILE_SPACE */
+@retval DB_SUCCESS           success
+@retval DB_OUT_OF_FILE_SPACE out of file-space */
 static dberr_t row_ins_index_entry_big_rec_func(
     trx_t *trx, const dtuple_t *entry, const big_rec_t *big_rec, ulint *offsets,
     mem_heap_t **heap, IF_DEBUG(const THD *thd, ) dict_index_t *index) {

storage/innobase/trx/trx0undo.cc

@@ -1542,9 +1542,9 @@ void trx_undo_mem_free(trx_undo_t *undo) /*!< in: the undo object to be freed */
 @param[out]  undo    the new undo log object, undefined if did not succeed
 @param[in]   mtr     mini-transation
 @retval DB_SUCCESS if successful in creating the new undo lob object,
-@retval DB_TOO_MANY_CONCURRENT_TRXS
-@retval DB_OUT_OF_FILE_SPACE
-@retval DB_OUT_OF_MEMORY */
+@retval DB_TOO_MANY_CONCURRENT_TRXS too many concurrent trxs
+@retval DB_OUT_OF_FILE_SPACE        out of file-space
+@retval DB_OUT_OF_MEMORY            out of memory */
 [[nodiscard]] static dberr_t trx_undo_create(
     trx_rseg_t *rseg, ulint type, trx_id_t trx_id, const XID *xid,
     trx_undo_t::Gtid_storage gtid_storage, trx_undo_t **undo, mtr_t *mtr) {

unittest/gunit/CMakeLists.txt

@@ -25,9 +25,11 @@ IF(NOT WITH_UNIT_TESTS)
 ENDIF()
 
 MSVC_CPPCHECK_DISABLE()
-# TODO: remove when all -Wdocumentation warnings are fixed.
-# - storage/innobase/
-DISABLE_DOCUMENTATION_WARNINGS()
+
+IF(NOT WITH_DEBUG)
+  # the innodb parts are documented assuming WITH_DEBUG (UNIV_DEBUG)
+  DISABLE_DOCUMENTATION_WARNINGS()
+ENDIF()
 
 # Some tests require Boost.
 INCLUDE_DIRECTORIES(SYSTEM ${BOOST_PATCHES_DIR} ${BOOST_INCLUDE_DIR})

utilities/CMakeLists.txt

@@ -23,9 +23,11 @@
 ADD_WSHADOW_WARNING()
 DISABLE_MISSING_PROFILE_WARNING()
 MSVC_CPPCHECK_DISABLE()
-# TODO: remove when all -Wdocumentation warnings are fixed.
-# - storage/innobase
-DISABLE_DOCUMENTATION_WARNINGS()
+
+IF(NOT WITH_DEBUG)
+  # the innodb parts are documented assuming WITH_DEBUG (UNIV_DEBUG)
+  DISABLE_DOCUMENTATION_WARNINGS()
+ENDIF()
 
 IF(NOT CMAKE_CROSSCOMPILING)
   MYSQL_ADD_EXECUTABLE(comp_err