Update doxygen annotations in plugin.h

Add doxygen markup so comments get picked up. Also fix minor typos and
expand documentation where relevant.

Signed-off-by: Trevor Gross <[email protected]>

include/mysql/plugin.h

@@ -14,6 +14,12 @@
  along with this program; if not, write to the Free Software
  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */
 
+/**
+ @file
+
+ Interfaces for creating server and client plugins.
+*/
+
 #ifndef MYSQL_PLUGIN_INCLUDED
 #define MYSQL_PLUGIN_INCLUDED
 
@@ -73,29 +79,33 @@ typedef struct st_mysql_xid MYSQL_XID;
  Plugin API. Common for all plugin types.
 */
 
-/* MySQL plugin interface version */
+/** MySQL plugin interface version */
 #define MYSQL_PLUGIN_INTERFACE_VERSION 0x0104
 
-/* MariaDB plugin interface version */
+/** MariaDB plugin interface version */
 #define MARIA_PLUGIN_INTERFACE_VERSION 0x010f
 
 /*
  The allowable types of plugins
 */
-#define MYSQL_UDF_PLUGIN 0 /* not implemented  */
+#define MYSQL_UDF_PLUGIN 0 /**< not implemented */
 #define MYSQL_STORAGE_ENGINE_PLUGIN 1
-#define MYSQL_FTPARSER_PLUGIN 2 /* Full-text parser plugin  */
+#define MYSQL_FTPARSER_PLUGIN 2 /**< Full-text parser plugin */
 #define MYSQL_DAEMON_PLUGIN 3
 #define MYSQL_INFORMATION_SCHEMA_PLUGIN 4
 #define MYSQL_AUDIT_PLUGIN 5
 #define MYSQL_REPLICATION_PLUGIN 6
 #define MYSQL_AUTHENTICATION_PLUGIN 7
-#define MYSQL_MAX_PLUGIN_TYPE_NUM 12 /* The number of plugin types  */
+#define MYSQL_MAX_PLUGIN_TYPE_NUM 12 /**< The number of plugin types */
 
 /* MariaDB plugin types */
-#define MariaDB_PASSWORD_VALIDATION_PLUGIN 8
+/** Client and server password validation */
+#define MariaDB_PASSWORD_VALIDATION_PLUGIN 8 
+/**< Encryption and key managment plugins */
 #define MariaDB_ENCRYPTION_PLUGIN 9
+/**< Plugins for SQL data storage types */
 #define MariaDB_DATA_TYPE_PLUGIN 10
+/**< Plugins for new native SQL functions */
 #define MariaDB_FUNCTION_PLUGIN 11
 
 /* We use the following strings to define licenses for plugins */
@@ -220,8 +230,8 @@ struct st_mysql_show_var SHOW_FUNC_ENTRY(const char *name,
  Constants for plugin flags.
  */
 
-#define PLUGIN_OPT_NO_INSTALL 1UL /* Not dynamically loadable */
-#define PLUGIN_OPT_NO_UNINSTALL 2UL /* Not dynamically unloadable */
+#define PLUGIN_OPT_NO_INSTALL 1UL /**< Not dynamically loadable */
+#define PLUGIN_OPT_NO_UNINSTALL 2UL /**< Not dynamically unloadable */
 
 
 /*
@@ -238,20 +248,20 @@ struct st_mysql_show_var SHOW_FUNC_ENTRY(const char *name,
 #define PLUGIN_VAR_SET 0x0007
 #define PLUGIN_VAR_DOUBLE 0x0008
 #define PLUGIN_VAR_UNSIGNED 0x0080
-#define PLUGIN_VAR_THDLOCAL 0x0100 /* Variable is per-connection */
-#define PLUGIN_VAR_READONLY 0x0200 /* Server variable is read only */
-#define PLUGIN_VAR_NOSYSVAR 0x0400 /* Not a server variable */
-#define PLUGIN_VAR_NOCMDOPT 0x0800 /* Not a command line option */
-#define PLUGIN_VAR_NOCMDARG 0x1000 /* No argument for cmd line */
-#define PLUGIN_VAR_RQCMDARG 0x0000 /* Argument required for cmd line */
-#define PLUGIN_VAR_OPCMDARG 0x2000 /* Argument optional for cmd line */
-#define PLUGIN_VAR_DEPRECATED 0x4000 /* Server variable is deprecated */
-#define PLUGIN_VAR_MEMALLOC 0x8000 /* String needs memory allocated */
+#define PLUGIN_VAR_THDLOCAL 0x0100 /**< Variable is per-connection */
+#define PLUGIN_VAR_READONLY 0x0200 /**< Server variable is read only */
+#define PLUGIN_VAR_NOSYSVAR 0x0400 /**< Not a server variable */
+#define PLUGIN_VAR_NOCMDOPT 0x0800 /**< Not a command line option */
+#define PLUGIN_VAR_NOCMDARG 0x1000 /**< No argument for cmd line */
+#define PLUGIN_VAR_RQCMDARG 0x0000 /**< Argument required for cmd line */
+#define PLUGIN_VAR_OPCMDARG 0x2000 /**< Argument optional for cmd line */
+#define PLUGIN_VAR_DEPRECATED 0x4000 /**< Server variable is deprecated */
+#define PLUGIN_VAR_MEMALLOC 0x8000 /**< String needs memory allocated */
 
 struct st_mysql_sys_var;
 struct st_mysql_value;
 
-/*
+/**
  SYNOPSIS
  (*mysql_var_check_func)()
  thd thread handle
@@ -274,7 +284,7 @@ typedef int (*mysql_var_check_func)(MYSQL_THD thd,
  struct st_mysql_sys_var *var,
  void *save, struct st_mysql_value *value);
 
-/*
+/**
  SYNOPSIS
  (*mysql_var_update_func)()
  thd thread handle
@@ -519,61 +529,61 @@ DECLARE_MYSQL_THDVAR_SIMPLE(name, double) = { \
  (*(MYSQL_SYSVAR_NAME(name).resolve(thd, MYSQL_SYSVAR_NAME(name).offset)))
 
 
-/*
+/**
  Plugin description structure.
 */
 
 struct st_mysql_plugin
 {
- int type; /* the plugin type (a MYSQL_XXX_PLUGIN value) */
- void *info; /* pointer to type-specific plugin descriptor */
- const char *name; /* plugin name */
- const char *author; /* plugin author (for I_S.PLUGINS) */
- const char *descr; /* general descriptive text (for I_S.PLUGINS) */
- int license; /* the plugin license (PLUGIN_LICENSE_XXX) */
- /*
+ int type; /**< the plugin type (a MYSQL_XXX_PLUGIN value) */
+ void *info; /**< pointer to type-specific plugin descriptor */
+ const char *name; /**< plugin name */
+ const char *author; /**< plugin author (for I_S.PLUGINS) */
+ const char *descr; /**< general descriptive text (for I_S.PLUGINS) */
+ int license; /**< the plugin license (PLUGIN_LICENSE_XXX) */
+ /**
  The function to invoke when plugin is loaded. Plugin
  initialisation done here should defer any ALTER TABLE queries to
  after the ddl recovery is done, in the signal_ddl_recovery_done()
  callback called by ha_signal_ddl_recovery_done().
  */
  int (*init)(void *);
- int (*deinit)(void *);/* the function to invoke when plugin is unloaded */
- unsigned int version; /* plugin version (for I_S.PLUGINS) */
+ int (*deinit)(void *);/**< the function to invoke when plugin is unloaded */
+ unsigned int version; /**< plugin version (for I_S.PLUGINS)  */
  struct st_mysql_show_var *status_vars;
  struct st_mysql_sys_var **system_vars;
- void * __reserved1; /* reserved for dependency checking */
- unsigned long flags; /* flags for plugin */
+ void * __reserved1; /**< reserved for dependency checking  */
+ unsigned long flags; /**< flags for plugin */
 };
 
-/*
+/**
  MariaDB extension for plugins declaration structure.
 
- It also copy current MySQL plugin fields to have more independency
+ It also copies current MySQL plugin fields to have more independency
  in plugins extension
 */
 
 struct st_maria_plugin
 {
- int type; /* the plugin type (a MYSQL_XXX_PLUGIN value) */
- void *info; /* pointer to type-specific plugin descriptor */
- const char *name; /* plugin name */
- const char *author; /* plugin author (for SHOW PLUGINS) */
- const char *descr; /* general descriptive text (for SHOW PLUGINS ) */
- int license; /* the plugin license (PLUGIN_LICENSE_XXX) */
- /*
+ int type; /**< the plugin type (a MYSQL_XXX_PLUGIN value) */
+ void *info; /**< pointer to type-specific plugin descriptor */
+ const char *name; /**< plugin name */
+ const char *author; /**< plugin author (for SHOW PLUGINS) */
+ const char *descr; /**< general descriptive text (for SHOW PLUGINS ) */
+ int license; /**< the plugin license (PLUGIN_LICENSE_XXX) */
+ /**
  The function to invoke when plugin is loaded. Plugin
  initialisation done here should defer any ALTER TABLE queries to
  after the ddl recovery is done, in the signal_ddl_recovery_done()
  callback called by ha_signal_ddl_recovery_done().
  */
  int (*init)(void *);
- int (*deinit)(void *);/* the function to invoke when plugin is unloaded */
- unsigned int version; /* plugin version (for SHOW PLUGINS) */
+ int (*deinit)(void *);/**< the function to invoke when plugin is unloaded */
+ unsigned int version; /**< plugin version (for SHOW PLUGINS) */
  struct st_mysql_show_var *status_vars;
  struct st_mysql_sys_var **system_vars;
- const char *version_info; /* plugin version string */
- unsigned int maturity; /* MariaDB_PLUGIN_MATURITY_XXX */
+ const char *version_info; /**< plugin version string */
+ unsigned int maturity;  /**< MariaDB_PLUGIN_MATURITY_XXX */
 };
 
 /*************************************************************************
@@ -650,6 +660,10 @@ struct handlerton;
  int interface_version;
  };
 
+#define MYSQL_VALUE_TYPE_STRING 0
+#define MYSQL_VALUE_TYPE_REAL 1
+#define MYSQL_VALUE_TYPE_INT 2
+
 /*************************************************************************
  st_mysql_value struct for reading values from mysqld.
  Used by server variables framework to parse user-provided values.
@@ -660,10 +674,6 @@ struct handlerton;
  if you need it to persist.
 */
 
-#define MYSQL_VALUE_TYPE_STRING 0
-#define MYSQL_VALUE_TYPE_REAL 1
-#define MYSQL_VALUE_TYPE_INT 2
-
 struct st_mysql_value
 {
  int (*value_type)(struct st_mysql_value *);
@@ -691,6 +701,7 @@ struct DDL_options_st *thd_ddl_options(const MYSQL_THD thd);
 void thd_storage_lock_wait(MYSQL_THD thd, long long value);
 int thd_tx_isolation(const MYSQL_THD thd);
 int thd_tx_is_read_only(const MYSQL_THD thd);
+
 /**
  Create a temporary file.