BUG#31354830 FIX DOXYGEN WARNINGS IN SRVGEN CODE

Fixed doxygen warnings reported by recent doxygen versions.

Changes in Doxyfile.in:
- upgraded config to doxygen 1.8.20,
  while commenting new options not understood by doxygen 1.8.13,
  for backward compatibility with 1.8.13.
- removed the obsolete TCL_SUBST option
- set EXTRACT_ANON_NSPACES to YES,
  which resolves many warnings related to code using anonymous namespace.
- excluded test code from the doxygen build.

Changes in the source code in general:
- removed duplicated page PAGE_COMPONENTS_REGISTRY
- fixed many doc duplication between declarations and definitions
- fixed some typos in doc
- fixed formatting of retval for tuples
- fixed unbalanced grouping commands

Tested with doxygen 1.8.20.

Approved by: Chris Powers <chris.powers@oracle.com>

Author: marcalff

Doxyfile.in

@@ -54,7 +54,7 @@
 ##
 ##===========================================================================
 
-# Doxyfile 1.8.17
+# Doxyfile 1.8.20
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -273,6 +273,14 @@ QT_AUTOBRIEF           = YES
 
 MULTILINE_CPP_IS_BRIEF = NO
 
+# By default Python docstrings are displayed as preformatted text and doxygen's
+# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the
+# doxygen's special commands can be used and the contents of the docstring
+# documentation blocks is shown as doxygen documentation.
+# The default value is: YES.
+
+# PYTHON_DOCSTRING       = YES
+
 # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the
 # documentation from any documented member that it re-implements.
 # The default value is: YES.
@@ -310,12 +318,6 @@ TAB_SIZE               = 8
 ALIASES                = "SQL{1}=<small>\1</small>" \
                          "B{1}=<b>\1</b>"
 
-# This tag can be used to specify a number of word-keyword mappings (TCL only).
-# A mapping has the form "name=value". For example adding "class=itcl::class"
-# will allow you to use the command class in the itcl::class meaning.
-
-TCL_SUBST              =
-
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
 # instance, some of the names that are used will be different. The list of all
@@ -357,13 +359,13 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # extension. Doxygen has a built-in mapping, but you can override or extend it
 # using this tag. The format is ext=language, where ext is a file extension, and
 # language is one of the parsers supported by doxygen: IDL, Java, JavaScript,
-# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice,
+# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL,
 # Fortran (fixed format Fortran: FortranFixed, free formatted Fortran:
 # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser
 # tries to guess whether the code is fixed or free formatted code, this is the
-# default for Fortran type files), VHDL, tcl. For instance to make doxygen treat
-# .inc files as Fortran files (default is PHP), and .f files as C (default is
-# Fortran), use: inc=Fortran f=C.
+# default for Fortran type files). For instance to make doxygen treat .inc files
+# as Fortran files (default is PHP), and .f files as C (default is Fortran),
+# use: inc=Fortran f=C.
 #
 # Note: For files without extension you can use no_extension as a placeholder.
 #
@@ -502,6 +504,19 @@ TYPEDEF_HIDES_STRUCT   = NO
 
 LOOKUP_CACHE_SIZE      = 2
 
+# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use
+# during processing. When set to 0 doxygen will based this on the number of
+# cores available in the system. You can set it explicitly to a value larger
+# than 0 to get more control over the balance between CPU load and processing
+# speed. At this moment only the input processing can be done using multiple
+# threads. Since this is still an experimental feature the default is set to 1,
+# which efficively disables parallel processing. Please report any issues you
+# encounter. Generating dot graphs in parallel is controlled by the
+# DOT_NUM_THREADS setting.
+# Minimum value: 0, maximum value: 32, default value: 1.
+
+# NUM_PROC_THREADS       = 1
+
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
@@ -563,7 +578,7 @@ EXTRACT_LOCAL_METHODS  = NO
 # are hidden.
 # The default value is: NO.
 
-EXTRACT_ANON_NSPACES   = NO
+EXTRACT_ANON_NSPACES   = YES
 
 # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
 # undocumented members inside documented classes or files. If set to NO these
@@ -606,7 +621,7 @@ INTERNAL_DOCS          = NO
 # names in lower-case letters. If set to YES, upper-case letters are also
 # allowed. This is useful if you have classes or files whose names only differ
 # in case and if your file system supports case sensitive file names. Windows
-# (including Cygwin) ands Mac users are advised to set this option to NO.
+# (including Cygwin) and Mac users are advised to set this option to NO.
 # The default value is: system dependent.
 
 CASE_SENSE_NAMES       = YES
@@ -940,7 +955,7 @@ INPUT_ENCODING         = UTF-8
 # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,
 # *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment),
 # *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen
-# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f, *.for, *.tcl, *.vhd,
+# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd,
 # *.vhdl, *.ucf, *.qsf and *.ice.
 
 FILE_PATTERNS          = *.c \
@@ -976,6 +991,7 @@ RECURSIVE              = YES
 
 EXCLUDE                = cmd-line-utils \
                          client/mysqlbinlog.cc \
+                         components/test \
                          extra \
                          generated \
                          include/mysqld_error.h \
@@ -984,6 +1000,8 @@ EXCLUDE                = cmd-line-utils \
                          internal \
                          libevent \
                          plugin/innodb_memcached/daemon_memcached/include/memcached \
+                         plugin/test_services \
+                         plugin/test_service_sql_api \
                          source_downloads \
                          sql/sql_hints.cc \
                          sql/sql_yacc.cc \
@@ -1101,7 +1119,6 @@ INPUT_FILTER           =
 FILTER_PATTERNS        = "*/sql/mysqld.cc=perl ./doxygen_resources/doxygen-filter-mysqld" \
                          "*/plugin/x/protocol/*.proto=perl ./doxygen_resources/doxygen-filter-proto"
 
-
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 # INPUT_FILTER) will also be used to filter the input files that are used for
 # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES).
@@ -1474,7 +1491,7 @@ CHM_FILE               =
 HHC_LOCATION           =
 
 # The GENERATE_CHI flag controls if a separate .chi index file is generated
-# (YES) or that it should be included in the master .chm file (NO).
+# (YES) or that it should be included in the main .chm file (NO).
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
 
@@ -1636,6 +1653,17 @@ TREEVIEW_WIDTH         = 250
 
 EXT_LINKS_IN_WINDOW    = NO
 
+# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg
+# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see
+# https://inkscape.org) to generate formulas as SVG images instead of PNGs for
+# the HTML output. These images will generally look nicer at scaled resolutions.
+# Possible values are: png (the default) and svg (looks nicer but requires the
+# pdf2svg or inkscape tool).
+# The default value is: png.
+# This tag requires that the tag GENERATE_HTML is set to YES.
+
+# HTML_FORMULA_FORMAT    = png
+
 # Use this tag to change the font size of LaTeX formulas included as images in
 # the HTML documentation. When you change the font size after a successful
 # doxygen run you need to manually remove any form_*.png images from the HTML
@@ -1691,7 +1719,7 @@ MATHJAX_FORMAT         = HTML-CSS
 # Content Delivery Network so you can quickly see the result without installing
 # MathJax. However, it is strongly recommended to install a local copy of
 # MathJax from https://www.mathjax.org before deployment.
-# The default value is: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/.
+# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2.
 # This tag requires that the tag USE_MATHJAX is set to YES.
 
 MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
@@ -1930,9 +1958,11 @@ LATEX_EXTRA_FILES      =
 
 PDF_HYPERLINKS         = YES
 
-# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
-# the PDF file directly from the LaTeX files. Set this option to YES, to get a
-# higher quality PDF documentation.
+# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as
+# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX
+# files. Set this option to YES, to get a higher quality PDF documentation.
+#
+# See also section LATEX_CMD_NAME for selecting the engine.
 # The default value is: YES.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 

components/libminchassis/minimal_chassis_runtime_error_imp.cc

@@ -24,13 +24,6 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */
 #include <mysql/components/service_implementation.h>
 #include <stdio.h>
 
-/**
-  This is the default implementation for emit api.
-  @param error_id    error ID.
-  @param flags error flags
-  @param args  va_list type, which hold the error message string.
-*/
-
 DEFINE_METHOD(void, mysql_runtime_error_imp::emit,
               (int error_id, int flags, va_list args)) {
   char buff[1024];

components/libminchassis/minimal_chassis_runtime_error_imp.h

@@ -28,13 +28,13 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */
 
 /**
   An default implementation of the mysql_runtime_error service for minimal
-  chassis library to reportthe error messages.
+  chassis library to report the error messages.
 */
 class mysql_runtime_error_imp {
  public:
   /**
     This function reports the given error to the caller.
-    @param error_id error id is used to retrive the error description.
+    @param error_id error id is used to retrieve the error description.
     @param flags    flags for the given error do decide where to print the error
     @param args     variable list arguments which holds error message format
                     string

components/libminchassis/registry_imp.h

@@ -33,22 +33,6 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */
 #include "mysql_service_implementation.h"
 #include "rwlock_scoped_lock.h"
 
-/**
-  @page PAGE_COMPONENTS_REGISTRY The Service Registry Service
-  The Service Registry is a central part of Components subsystem. It maintains
-  a list of the Service Implementations and allow acquiring them by any actor
-  that has a reference to main Registry Service Implementation. For each Service
-  a reference counter is maintained to make sure no one can remove any Service
-  Implementation being actively used.
-  The Service Implementations can be acquired by the Service name or by the full
-  Service Implementation name.
-  For each Service a default Service Implementation is distinguished, the first
-  one to be added, but it is possible to change it at will at any point.
-
-  A convenient RAII-style wrapper on Service acquisition and automatic release
-  is provided, the my_service<T> class.
-*/
-
 typedef std::map<const char *, mysql_service_implementation *, c_string_less>
     my_service_registry;
 

libmysql/authentication_ldap/auth_ldap_kerberos.h

@@ -64,9 +64,8 @@ class Kerberos {
     it again.
 
     @return
-      @retval true, If function is successfully able to obtain and store
-    credentials.
-      @retval false, If function is failed to obtain and store credentials.
+      @retval true Successfully able to obtain and store credentials.
+      @retval false Failed to obtain and store credentials.
   */
   bool obtain_store_credentials();
   /**
@@ -75,8 +74,8 @@ class Kerberos {
     MySQL client, This method can be used to get the user name  and use for
     authentication.
     @return
-      @retval true, If function is successfully able to get user name.
-      @retval false, If function is failed to get user name.
+      @retval true Successfully able to get user name.
+      @retval false Failed to get user name.
   */
   bool get_user_name(std::string *name);
   void destroy_credentials();
@@ -90,9 +89,9 @@ class Kerberos {
     This function creates kerberos context, initializes credentials cache and
     user principal.
     @return
-      @retval true, If all the required kerberos objects like context,
-    credentials cache and  user principal are initialized correctly.
-      @retval false, If required kerberos objects are failed to initialized.
+      @retval true All the required kerberos objects like context,
+    credentials cache and user principal are initialized correctly.
+      @retval false Required kerberos objects failed to initialized.
   */
   bool setup();
   /**

sql/auth/dynamic_privileges_impl.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2017, 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,
@@ -36,15 +36,6 @@ class dynamic_privilege_services_impl {
   static DEFINE_BOOL_METHOD(register_privilege, (const char *privilege_str,
                                                  size_t privilege_str_len));
 
-  /**
-    Unregister a previously registered privilege object identifier so that it no
-    longer can be used in GRANT statements.
-    @param privilege_str Privilege object ID
-    @param privilege_str_len The length of the string (not including \0)
-    @return Error state
-       @retval true Operation was not successful
-       @retval false Success
-  */
   static DEFINE_BOOL_METHOD(unregister_privilege, (const char *privilege_str,
                                                    size_t privilege_str_len));
 

sql/auth/sql_auth_cache.cc

@@ -3208,20 +3208,6 @@ uint64 Acl_cache::version() { return m_role_graph_version.load(); }
 
 int32 Acl_cache::size() { return m_cache.count.load(); }
 
-/**
-  Finds an Acl_map entry in the Acl_cache and increase its reference count.
-  If no Acl_map is located, a new one is created with reference count one.
-  The Acl_map is returned to the caller.
-
-  @param sctx The target Security_context
-  @param uid The target authid
-  @param active_roles A list of active roles
-
-  @return A pointer to an Acl_map
-    @retval !NULL Success
-    @retval NULL A fatal OOM error happened.
-*/
-
 Acl_map *Acl_cache::checkout_acl_map(Security_context *sctx, Auth_id_ref &uid,
                                      List_of_auth_id_refs &active_roles) {
   DBUG_TRACE;

sql/auth/sql_auth_cache.h

@@ -597,7 +597,13 @@ class Acl_cache {
     A new object will also be created if the role graph version counter is
     different than the acl map object's version.
 
-    @param uid user id
+    @param sctx The target Security_context
+    @param uid The target authid
+    @param active_roles A list of active roles
+
+    @return A pointer to an Acl_map
+    @retval !NULL Success
+    @retval NULL A fatal OOM error happened.
   */
   Acl_map *checkout_acl_map(Security_context *sctx, Auth_id_ref &uid,
                             List_of_auth_id_refs &active_roles);

sql/auth/sql_security_ctx.cc

@@ -640,10 +640,10 @@ bool Security_context::any_table_acl(const LEX_CSTRING &db) {
   @param [in] priv      privilege to check
   @param [in] priv_len  length of privilege
 
-  @returns  pair/<has_privilege, has_with_grant_option/>
-    @retval /<true, true/>  has required privilege with grant option
-    @retval /<true, false/> has required privilege without grant option
-    @retval /<false, false/> does not have the required privilege
+  @returns  pair@<has_privilege, has_with_grant_option@>
+    @retval "<true, true>"  has required privilege with grant option
+    @retval "<true, false>" has required privilege without grant option
+    @retval "<false, false>" does not have the required privilege
 */
 std::pair<bool, bool> Security_context::has_global_grant(const char *priv,
                                                          size_t priv_len) {
@@ -692,10 +692,10 @@ std::pair<bool, bool> Security_context::has_global_grant(const char *priv,
                                   roles granted to it irrespective the roles are
                                   active or not.
 
-  @returns  pair/<has_privilege, has_with_grant_option/>
-    @retval /<true, true/>  has required privilege with grant option
-    @retval /<true, false/> has required privilege without grant option
-    @retval /<false, false/> does not have the required privilege, OR
+  @returns  pair@<has_privilege, has_with_grant_option@>
+    @retval "<true, true>"  has required privilege with grant option
+    @retval "<true, false>" has required privilege without grant option
+    @retval "<false, false>" does not have the required privilege, OR
                              auth_id does not exist.
 */
 std::pair<bool, bool> Security_context::has_global_grant(
@@ -1149,10 +1149,10 @@ ulong Security_context::filter_access(const ulong access,
                           true  - privileges granted directly or coming through
                                   roles granted to it irrespective the roles are
                                   active or not.
-  @returns  pair/<has_privilege, has_with_grant_option/>
-    @retval /<true, true/>   has required privilege with grant option
-    @retval /<true, false/>  has required privilege without grant option
-    @retval /<false, false/> does not have the required privilege
+  @returns  pair@<has_privilege, has_with_grant_option@>
+    @retval "<true, true>"   has required privilege with grant option
+    @retval "<true, false>"  has required privilege without grant option
+    @retval "<false, false>" does not have the required privilege
 */
 std::pair<bool, bool> Security_context::fetch_global_grant(
     const ACL_USER &acl_user, const std::string &privilege,