Doxygenize comments.

16 files changed, 313 insertions, 281 deletions

diff --git a/sql/my_decimal.h b/sql/my_decimal.h
index 800ae23425b..1885036f42b 100644
--- a/sql/my_decimal.h
+++ b/sql/my_decimal.h
@@ -13,7 +13,9 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
+/**
+  @file
+
   It is interface module to fixed precision decimals library.
 
   Most functions use 'uint mask' as parameter, if during operation error
@@ -34,14 +36,14 @@ C_MODE_END
 #define DECIMAL_LONG_DIGITS 10
 #define DECIMAL_LONG3_DIGITS 8
 
-/* maximum length of buffer in our big digits (uint32) */
+/** maximum length of buffer in our big digits (uint32). */
 #define DECIMAL_BUFF_LENGTH 9
 
 /* the number of digits that my_decimal can possibly contain */
 #define DECIMAL_MAX_POSSIBLE_PRECISION (DECIMAL_BUFF_LENGTH * 9)
 
 
-/*
+/**
   maximum guaranteed precision of number in decimal digits (number of our
   digits * number of decimal digits in one our big digit - number of decimal
   digits in one our big digit decreased by 1 (because we always put decimal
@@ -51,13 +53,14 @@ C_MODE_END
 #define DECIMAL_MAX_SCALE 30
 #define DECIMAL_NOT_SPECIFIED 31
 
-/*
+/**
   maximum length of string representation (number of maximum decimal
   digits + 1 position for sign + 1 position for decimal point)
 */
 #define DECIMAL_MAX_STR_LENGTH (DECIMAL_MAX_POSSIBLE_PRECISION + 2)
-/*
-  maximum size of packet length
+
+/**
+  maximum size of packet length.
 */
 #define DECIMAL_MAX_FIELD_SIZE DECIMAL_MAX_PRECISION
 
@@ -78,11 +81,12 @@ inline int my_decimal_int_part(uint precision, uint decimals)
 }
 
 
-/*
-  my_decimal class limits 'decimal_t' type to what we need in MySQL
+/**
+  my_decimal class limits 'decimal_t' type to what we need in MySQL.
+
   It contains internally all necessary space needed by the instance so
   no extra memory is needed. One should call fix_buffer_pointer() function
-  when he moves my_decimal objects in memory
+  when he moves my_decimal objects in memory.
 */
 
 class my_decimal :public decimal_t
@@ -384,7 +388,10 @@ int my_decimal_mod(uint mask, my_decimal *res, const my_decimal *a,
 }
 
 
-/* Returns -1 if a<b, 1 if a>b and 0 if a==b */
+/**
+  @return
+    -1 if a<b, 1 if a>b and 0 if a==b
+*/
 inline
 int my_decimal_cmp(const my_decimal *a, const my_decimal *b)
 {
diff --git a/sql/mysql_priv.h b/sql/mysql_priv.h
index dfea3060cee..034e548cfbd 100644
--- a/sql/mysql_priv.h
+++ b/sql/mysql_priv.h
@@ -13,10 +13,13 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
+/**
+  @file
+
+  @details
   Mostly this file is used in the server. But a little part of it is used in
   mysqlbinlog too (definition of SELECT_DISTINCT and others).
-  The consequence is that 90% of the file is wrapped in #ifndef MYSQL_CLIENT,
+  The consequence is that 90% of the file is wrapped in \#ifndef MYSQL_CLIENT,
   except the part which must be in the server and in the client.
 */
 
@@ -253,12 +256,12 @@ protected:
  Feel free to raise this by the smallest amount you can to get the
  "execution_constants" test to pass.
  */
-#define STACK_MIN_SIZE          12000   // Abort if less stack during eval.
+#define STACK_MIN_SIZE          12000   ///< Abort if less stack during eval.
 
 #define STACK_MIN_SIZE_FOR_OPEN 1024*80
-#define STACK_BUFF_ALLOC        352     // For stack overrun checks
+#define STACK_BUFF_ALLOC        352     ///< For stack overrun checks
 #ifndef MYSQLD_NET_RETRY_COUNT
-#define MYSQLD_NET_RETRY_COUNT  10	// Abort read after this many int.
+#define MYSQLD_NET_RETRY_COUNT  10	///< Abort read after this many int.
 #endif
 #define TEMP_POOL_SIZE          128
 
@@ -282,14 +285,14 @@ protected:
 #define MIN_ROWS_TO_USE_TABLE_CACHE	 100
 #define MIN_ROWS_TO_USE_BULK_INSERT	 100
 
-/*
+/**
   The following is used to decide if MySQL should use table scanning
   instead of reading with keys.  The number says how many evaluation of the
   WHERE clause is comparable to reading one extra row from a table.
 */
 #define TIME_FOR_COMPARE   5	// 5 compares == one read
 
-/*
+/**
   Number of comparisons of table rowids equivalent to reading one row from a 
   table.
 */
@@ -309,17 +312,17 @@ protected:
 #define DISK_SEEK_PROP_COST ((double)0.5/BLOCKS_IN_AVG_SEEK)
 
 
-/*
+/**
   Number of rows in a reference table when refereed through a not unique key.
   This value is only used when we don't know anything about the key
   distribution.
 */
 #define MATCHING_ROWS_IN_OTHER_TABLE 10
 
-/* Don't pack string keys shorter than this (if PACK_KEYS=1 isn't used) */
+/** Don't pack string keys shorter than this (if PACK_KEYS=1 isn't used). */
 #define KEY_DEFAULT_PACK_LENGTH 8
 
-/* Characters shown for the command in 'show processlist' */
+/** Characters shown for the command in 'show processlist'. */
 #define PROCESS_LIST_WIDTH 100
 /* Characters shown for the command in 'information_schema.processlist' */
 #define PROCESS_LIST_INFO_WIDTH 65535
@@ -335,11 +338,11 @@ protected:
 
 /* The following can also be changed from the command line */
 #define DEFAULT_CONCURRENCY	10
-#define DELAYED_LIMIT		100		/* pause after xxx inserts */
+#define DELAYED_LIMIT		100		/**< pause after xxx inserts */
 #define DELAYED_QUEUE_SIZE	1000
-#define DELAYED_WAIT_TIMEOUT	5*60		/* Wait for delayed insert */
-#define FLUSH_TIME		0		/* Don't flush tables */
-#define MAX_CONNECT_ERRORS	10		// errors before disabling host
+#define DELAYED_WAIT_TIMEOUT	5*60		/**< Wait for delayed insert */
+#define FLUSH_TIME		0		/**< Don't flush tables */
+#define MAX_CONNECT_ERRORS	10		///< errors before disabling host
 
 #ifdef __NETWARE__
 #define IF_NETWARE(A,B) A
@@ -349,7 +352,7 @@ protected:
 
 #if defined(__WIN__)
 #undef	FLUSH_TIME
-#define FLUSH_TIME	1800			/* Flush every half hour */
+#define FLUSH_TIME	1800			/**< Flush every half hour */
 
 #define INTERRUPT_PRIOR -2
 #define CONNECT_PRIOR	-1
@@ -368,12 +371,12 @@ protected:
 #define TEST_MIT_THREAD		4
 #define TEST_BLOCKING		8
 #define TEST_KEEP_TMP_TABLES	16
-#define TEST_READCHECK		64	/* Force use of readcheck */
+#define TEST_READCHECK		64	/**< Force use of readcheck */
 #define TEST_NO_EXTRA		128
-#define TEST_CORE_ON_SIGNAL	256	/* Give core if signal */
+#define TEST_CORE_ON_SIGNAL	256	/**< Give core if signal */
 #define TEST_NO_STACKTRACE	512
-#define TEST_SIGINT		1024	/* Allow sigint on threads */
-#define TEST_SYNCHRONIZATION    2048    /* get server to do sleep in
+#define TEST_SIGINT		1024	/**< Allow sigint on threads */
+#define TEST_SYNCHRONIZATION    2048    /**< get server to do sleep in
                                            some places */
 #endif
 
@@ -423,26 +426,26 @@ protected:
 /* The following is used to detect a conflict with DISTINCT */
 #define SELECT_ALL              (ULL(1) << 24)    // SELECT, user, parser
 
-/* The following can be set when importing tables in a 'wrong order'
+/** The following can be set when importing tables in a 'wrong order'
    to suppress foreign key checks */
 #define OPTION_NO_FOREIGN_KEY_CHECKS    (ULL(1) << 26) // THD, user, binlog
-/* The following speeds up inserts to InnoDB tables by suppressing unique
+/** The following speeds up inserts to InnoDB tables by suppressing unique
    key checks in some cases */
 #define OPTION_RELAXED_UNIQUE_CHECKS    (ULL(1) << 27) // THD, user, binlog
 #define SELECT_NO_UNLOCK                (ULL(1) << 28) // SELECT, intern
 #define OPTION_SCHEMA_TABLE             (ULL(1) << 29) // SELECT, intern
-/* Flag set if setup_tables already done */
+/** Flag set if setup_tables already done */
 #define OPTION_SETUP_TABLES_DONE        (ULL(1) << 30) // intern
-/* If not set then the thread will ignore all warnings with level notes. */
+/** If not set then the thread will ignore all warnings with level notes. */
 #define OPTION_SQL_NOTES                (ULL(1) << 31) // THD, user
-/* 
+/**
   Force the used temporary table to be a MyISAM table (because we will use
   fulltext functions when reading from it.
 */
 #define TMP_TABLE_FORCE_MYISAM          (ULL(1) << 32)
 
 
-/*
+/**
   Maximum length of time zone name that we support
   (Time zone name is char(64) in db). mysqlbinlog needs it.
 */
@@ -505,9 +508,9 @@ protected:
 #define UNCACHEABLE_DEPENDENT   1
 #define UNCACHEABLE_RAND        2
 #define UNCACHEABLE_SIDEEFFECT	4
-// forcing to save JOIN for explain
+/// forcing to save JOIN for explain
 #define UNCACHEABLE_EXPLAIN     8
-/* Don't evaluate subqueries in prepare even if they're not correlated */
+/** Don't evaluate subqueries in prepare even if they're not correlated */
 #define UNCACHEABLE_PREPARE    16
 /* For uncorrelated SELECT in an UNION with some correlated SELECTs */
 #define UNCACHEABLE_UNITED     32
@@ -515,7 +518,7 @@ protected:
 /* Used to check GROUP BY list in the MODE_ONLY_FULL_GROUP_BY mode */
 #define UNDEF_POS (-1)
 #ifdef EXTRA_DEBUG
-/*
+/**
   Sync points allow us to force the server to reach a certain line of code
   and block there until the client tells the server it is ok to go on.
   The client tells the server to block with SELECT GET_LOCK()
@@ -551,7 +554,7 @@ void view_store_options(THD *thd, TABLE_LIST *table, String *buff);
 
 #define portable_sizeof_char_ptr 8
 
-#define tmp_file_prefix "#sql"			/* Prefix for tmp tables */
+#define tmp_file_prefix "#sql"			/**< Prefix for tmp tables */
 #define tmp_file_prefix_length 4
 
 /* Flags for calc_week() function.  */
@@ -586,9 +589,9 @@ enum enum_check_fields
   CHECK_FIELD_WARN,
   CHECK_FIELD_ERROR_FOR_NULL
 };
-                                  
-/* Struct to handle simple linked lists */
 
+                                  
+/** Struct to handle simple linked lists. */
 typedef struct st_sql_list {
   uint elements;
   uchar *first;
@@ -2192,16 +2195,15 @@ Item * all_any_subquery_creator(Item *left_expr,
 				bool all,
 				SELECT_LEX *select_lex);
 
-/*
-  clean/setup table fields and map
+/**
+  clean/setup table fields and map.
 
-  SYNOPSYS
-    setup_table_map()
-    table - TABLE structure pointer (which should be setup)
-    table_list TABLE_LIST structure pointer (owner of TABLE)
-    tablenr - table number
+  @param table        TABLE structure pointer (which should be setup)
+  @param table_list   TABLE_LIST structure pointer (owner of TABLE)
+  @param tablenr     table number
 */
 
+
 inline void setup_table_map(TABLE *table, TABLE_LIST *table_list, uint tablenr)
 {
   table->used_fields= 0;
@@ -2223,10 +2225,8 @@ inline void setup_table_map(TABLE *table, TABLE_LIST *table_list, uint tablenr)
 }
 
 
-/*
-  SYNOPSYS
-    hexchar_to_int()
-    convert a hex digit into number
+/**
+  convert a hex digit into number.
 */
 
 inline int hexchar_to_int(char c)
@@ -2239,11 +2239,9 @@ inline int hexchar_to_int(char c)
   return -1;
 }
 
-/*
-  is_user_table()
-  return true if the table was created explicitly
+/**
+  return true if the table was created explicitly.
 */
-
 inline bool is_user_table(TABLE * table)
 {
   const char *name= table->s->table_name.str;
diff --git a/sql/mysqld_suffix.h b/sql/mysqld_suffix.h
index b348f272db1..654d7cf88c1 100644
--- a/sql/mysqld_suffix.h
+++ b/sql/mysqld_suffix.h
@@ -13,8 +13,11 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
-  Set MYSQL_SERVER_SUFFIX_STR
+/**
+  @file
+
+  Set MYSQL_SERVER_SUFFIX_STR.
+
   The following code is quite ugly as there is no portable way to easily set a
   string to the value of a macro
 */
diff --git a/sql/nt_servc.h b/sql/nt_servc.h
index a3c12569114..525f709388b 100644
--- a/sql/nt_servc.h
+++ b/sql/nt_servc.h
@@ -1,8 +1,12 @@
-/* ------------------------------------------------------------------------
-   Windows NT Service class library
-   Copyright Abandoned 1998 Irena Pancirov - Irnet Snc
-   This file is public domain and comes with NO WARRANTY of any kind
- -------------------------------------------------------------------------- */
+/**
+  @file
+
+  @brief
+  Windows NT Service class library
+
+  Copyright Abandoned 1998 Irena Pancirov - Irnet Snc
+  This file is public domain and comes with NO WARRANTY of any kind
+*/
 
 // main application thread
 typedef void (*THREAD_FC)(void *);
@@ -13,7 +17,7 @@ class NTService
     NTService();
    ~NTService();
 
-    BOOL    bOsNT;	      // true if OS is NT, false for Win95
+    BOOL    bOsNT;	      ///< true if OS is NT, false for Win95
     //install optinos
     DWORD   dwDesiredAccess;
     DWORD   dwServiceType;
diff --git a/sql/parse_file.h b/sql/parse_file.h
index 91700959681..30c902478b8 100644
--- a/sql/parse_file.h
+++ b/sql/parse_file.h
@@ -20,27 +20,27 @@
 #define PARSE_FILE_TIMESTAMPLENGTH 19
 
 enum file_opt_type {
-  FILE_OPTIONS_STRING,		/* String (LEX_STRING) */
-  FILE_OPTIONS_ESTRING,		/* Escaped string (LEX_STRING) */
-  FILE_OPTIONS_ULONGLONG,	/* ulonglong parameter (ulonglong) */
-  FILE_OPTIONS_REV,		/* Revision version number (ulonglong) */
-  FILE_OPTIONS_TIMESTAMP,	/* timestamp (LEX_STRING have to be
+  FILE_OPTIONS_STRING,		/**< String (LEX_STRING) */
+  FILE_OPTIONS_ESTRING,		/**< Escaped string (LEX_STRING) */
+  FILE_OPTIONS_ULONGLONG,	/**< ulonglong parameter (ulonglong) */
+  FILE_OPTIONS_REV,		/**< Revision version number (ulonglong) */
+  FILE_OPTIONS_TIMESTAMP,	/**< timestamp (LEX_STRING have to be
 				   allocated with length 20 (19+1) */
-  FILE_OPTIONS_STRLIST,         /* list of escaped strings
+  FILE_OPTIONS_STRLIST,         /**< list of escaped strings
                                    (List<LEX_STRING>) */
-  FILE_OPTIONS_ULLLIST          /* list of ulonglong values
+  FILE_OPTIONS_ULLLIST          /**< list of ulonglong values
                                    (List<ulonglong>) */
 };
 
 struct File_option
 {
-  LEX_STRING name;		/* Name of the option */
-  int offset;			/* offset to base address of value */
-  file_opt_type type;		/* Option type */
+  LEX_STRING name;		/**< Name of the option */
+  int offset;			/**< offset to base address of value */
+  file_opt_type type;		/**< Option type */
 };
 
 
-/*
+/**
   This hook used to catch no longer supported keys and process them for
   backward compatibility.
 */
@@ -55,7 +55,7 @@ public:
 };
 
 
-/* Dummy hook for parsers which do not need hook for unknown keys */
+/** Dummy hook for parsers which do not need hook for unknown keys. */
 
 class File_parser_dummy_hook: public Unknown_key_hook
 {
diff --git a/sql/procedure.h b/sql/procedure.h
index 6a731766046..4578fcb87f1 100644
--- a/sql/procedure.h
+++ b/sql/procedure.h
@@ -20,8 +20,8 @@
 #pragma interface				/* gcc class implementation */
 #endif
 
-#define PROC_NO_SORT 1				/* Bits in flags */
-#define PROC_GROUP   2				/* proc must have group */
+#define PROC_NO_SORT 1				/**< Bits in flags */
+#define PROC_GROUP   2				/**< proc must have group */
 
 /* Procedure items used by procedures to store values for send_fields */
 
diff --git a/sql/protocol.h b/sql/protocol.h
index 46a2b6d36b6..853cca0f769 100644
--- a/sql/protocol.h
+++ b/sql/protocol.h
@@ -110,7 +110,7 @@ public:
 };
 
 
-/* Class used for the old (MySQL 4.0 protocol) */
+/** Class used for the old (MySQL 4.0 protocol). */
 
 class Protocol_text :public Protocol
 {
diff --git a/sql/sp_head.h b/sql/sp_head.h
index 3a8b41acd4c..d0d4f92ae67 100644
--- a/sql/sp_head.h
+++ b/sql/sp_head.h
@@ -109,7 +109,7 @@ public:
   LEX_STRING m_db;
   LEX_STRING m_name;
   LEX_STRING m_qname;
-  /*
+  /**
     Key representing routine in the set of stored routines used by statement.
     Consists of 1-byte routine type and m_qname (which usually refences to
     same buffer). Note that one must complete initialization of the key by
@@ -125,7 +125,7 @@ public:
     m_qname.length= m_sroutines_key.length= 0;
   }
 
-  /*
+  /**
     Creates temporary sp_name object from key, used mainly
     for SP-cache lookups.
   */
@@ -158,12 +158,12 @@ check_routine_name(LEX_STRING *ident);
 
 class sp_head :private Query_arena
 {
-  sp_head(const sp_head &);	/* Prevent use of these */
+  sp_head(const sp_head &);	/**< Prevent use of these */
   void operator=(sp_head &);
 
   MEM_ROOT main_mem_root;
 public:
-  /* Possible values of m_flags */
+  /** Possible values of m_flags */
   enum {
     HAS_RETURN= 1,              // For FUNCTIONs only: is set if has RETURN
     MULTI_RESULTS= 8,           // Is set if a procedure with SELECT(s)
@@ -179,16 +179,16 @@ public:
     HAS_SQLCOM_FLUSH= 4096
   };
 
-  /* TYPE_ENUM_FUNCTION, TYPE_ENUM_PROCEDURE or TYPE_ENUM_TRIGGER */
+  /** TYPE_ENUM_FUNCTION, TYPE_ENUM_PROCEDURE or TYPE_ENUM_TRIGGER */
   int m_type;
   uint m_flags;                 // Boolean attributes of a stored routine
 
-  Create_field m_return_field_def; /* This is used for FUNCTIONs only. */
+  Create_field m_return_field_def; /**< This is used for FUNCTIONs only. */
 
-  const char *m_tmp_query;	// Temporary pointer to sub query string
+  const char *m_tmp_query;	///< Temporary pointer to sub query string
   st_sp_chistics *m_chistics;
-  ulong m_sql_mode;		// For SHOW CREATE and execution
-  LEX_STRING m_qname;		// db.name
+  ulong m_sql_mode;		///< For SHOW CREATE and execution
+  LEX_STRING m_qname;		///< db.name
   /**
     Key representing routine in the set of stored routines used by statement.
     [routine_type]db.name
@@ -220,20 +220,20 @@ public:
 
   longlong m_created;
   longlong m_modified;
-  /* Recursion level of the current SP instance. The levels are numbered from 0 */
+  /** Recursion level of the current SP instance. The levels are numbered from 0 */
   ulong m_recursion_level;
-  /*
+  /**
     A list of diferent recursion level instances for the same procedure.
     For every recursion level we have a sp_head instance. This instances
     connected in the list. The list ordered by increasing recursion level
     (m_recursion_level).
   */
   sp_head *m_next_cached_sp;
-  /*
+  /**
     Pointer to the first element of the above list
   */
   sp_head *m_first_instance;
-  /*
+  /**
     Pointer to the first free (non-INVOKED) routine in the list of
     cached instances for this SP. This pointer is set only for the first
     SP in the list of instences (see above m_first_cached_sp pointer).
@@ -241,12 +241,12 @@ public:
     For non-first instance value of this pointer meanless (point to itself);
   */
   sp_head *m_first_free_instance;
-  /*
+  /**
     Pointer to the last element in the list of instances of the SP.
     For non-first instance value of this pointer meanless (point to itself);
   */
   sp_head *m_last_cached_sp;
-  /*
+  /**
     Set containing names of stored routines used by this routine.
     Note that unlike elements of similar set for statement elements of this
     set are not linked in one list. Because of this we are able save memory
@@ -276,11 +276,11 @@ public:
 
   sp_head();
 
-  // Initialize after we have reset mem_root
+  /// Initialize after we have reset mem_root
   void
   init(LEX *lex);
 
-  /* Copy sp name from parser. */
+  /** Copy sp name from parser. */
   void
   init_sp_name(THD *thd, sp_name *spname);
 
@@ -297,7 +297,7 @@ public:
 
   virtual ~sp_head();
 
-  // Free memory
+  /// Free memory
   void
   destroy();
 
@@ -334,33 +334,41 @@ public:
     return i;
   }
 
-  // Resets lex in 'thd' and keeps a copy of the old one.
+  /*
+    Resets lex in 'thd' and keeps a copy of the old one.
+
+    @todo Conflicting comment in sp_head.cc
+  */
   void
   reset_lex(THD *thd);
 
-  // Restores lex in 'thd' from our copy, but keeps some status from the
-  // one in 'thd', like ptr, tables, fields, etc.
+  /**
+    Restores lex in 'thd' from our copy, but keeps some status from the
+    one in 'thd', like ptr, tables, fields, etc.
+
+    @todo Conflicting comment in sp_head.cc
+  */
   void
   restore_lex(THD *thd);
 
-  // Put the instruction on the backpatch list, associated with the label.
+  /// Put the instruction on the backpatch list, associated with the label.
   void
   push_backpatch(sp_instr *, struct sp_label *);
 
-  // Update all instruction with this label in the backpatch list to
-  // the current position.
+  /// Update all instruction with this label in the backpatch list to
+  /// the current position.
   void
   backpatch(struct sp_label *);
 
-  // Start a new cont. backpatch level. If 'i' is NULL, the level is just incr.
+  /// Start a new cont. backpatch level. If 'i' is NULL, the level is just incr.
   void
   new_cont_backpatch(sp_instr_opt_meta *i);
 
-  // Add an instruction to the current level
+  /// Add an instruction to the current level
   void
   add_cont_backpatch(sp_instr_opt_meta *i);
 
-  // Backpatch (and pop) the current level to the current position.
+  /// Backpatch (and pop) the current level to the current position.
   void
   do_cont_backpatch();
 
@@ -423,7 +431,7 @@ public:
                                      TABLE_LIST ***query_tables_last_ptr,
                                      TABLE_LIST *belong_to_view);
 
-  /*
+  /**
     Check if this stored routine contains statements disallowed
     in a stored function or trigger, and set an appropriate error message
     if this is the case.
@@ -472,19 +480,19 @@ public:
 
 private:
 
-  MEM_ROOT *m_thd_root;		// Temp. store for thd's mem_root
-  THD *m_thd;			// Set if we have reset mem_root
+  MEM_ROOT *m_thd_root;		///< Temp. store for thd's mem_root
+  THD *m_thd;			///< Set if we have reset mem_root
 
-  sp_pcontext *m_pcont;		// Parse context
-  List<LEX> m_lex;		// Temp. store for the other lex
-  DYNAMIC_ARRAY m_instr;	// The "instructions"
+  sp_pcontext *m_pcont;		///< Parse context
+  List<LEX> m_lex;		///< Temp. store for the other lex
+  DYNAMIC_ARRAY m_instr;	///< The "instructions"
   typedef struct
   {
     struct sp_label *lab;
     sp_instr *instr;
   } bp_t;
-  List<bp_t> m_backpatch;	// Instructions needing backpatching
-  /*
+  List<bp_t> m_backpatch;	///< Instructions needing backpatching
+  /**
     We need a special list for backpatching of instructions with a continue
     destination (in the case of a continue handler catching an error in
     the test), since it would otherwise interfere with the normal backpatch
@@ -492,15 +500,16 @@ private:
     which are to be patched differently.
     Since these occur in a more restricted way (always the same "level" in
     the code), we don't need the label.
-   */
+  */
   List<sp_instr_opt_meta> m_cont_backpatch;
   uint m_cont_level;            // The current cont. backpatch level
 
-  /*
+  /**
     Multi-set representing optimized list of tables to be locked by this
     routine. Does not include tables which are used by invoked routines.
 
-    Note: for prelocking-free SPs this multiset is constructed too.
+    @note
+    For prelocking-free SPs this multiset is constructed too.
     We do so because the same instance of sp_head may be called both
     in prelocked mode and in non-prelocked mode.
   */
@@ -515,7 +524,7 @@ private:
   */
   void opt_mark();
 
-  /*
+  /**
     Merge the list of tables used by query into the multi-set of tables used
     by routine.
   */
@@ -529,16 +538,16 @@ private:
 
 class sp_instr :public Query_arena, public Sql_alloc
 {
-  sp_instr(const sp_instr &);	/* Prevent use of these */
+  sp_instr(const sp_instr &);	/**< Prevent use of these */
   void operator=(sp_instr &);
 
 public:
 
   uint marked;
-  uint m_ip;			// My index
-  sp_pcontext *m_ctx;		// My parse context
+  uint m_ip;			///< My index
+  sp_pcontext *m_ctx;		///< My parse context
 
-  // Should give each a name or type code for debugging purposes?
+  /// Should give each a name or type code for debugging purposes?
   sp_instr(uint ip, sp_pcontext *ctx)
     :Query_arena(0, INITIALIZED_FOR_SP), marked(0), m_ip(ip), m_ctx(ctx)
   {}
@@ -547,21 +556,19 @@ public:
   { free_items(); }
 
 
-  /*
+  /**
     Execute this instruction
 
-    SYNOPSIS
-       execute()
-         thd        Thread handle
-         nextp  OUT index of the next instruction to execute. (For most
-                    instructions this will be the instruction following this
-                    one). Note that this parameter is undefined in case of
-                    errors, use get_cont_dest() to find the continuation
-                    instruction for CONTINUE error handlers.
-
-     RETURN
-       0      on success,
-       other  if some error occurred
+   
+    @param thd         Thread handle
+    @param[out] nextp  index of the next instruction to execute. (For most
+                       instructions this will be the instruction following this
+                       one). Note that this parameter is undefined in case of
+                       errors, use get_cont_dest() to find the continuation
+                       instruction for CONTINUE error handlers.
+   
+    @retval 0      on success, 
+    @retval other  if some error occured
   */
 
   virtual int execute(THD *thd, uint *nextp) = 0;
@@ -599,7 +606,7 @@ public:
   virtual void backpatch(uint dest, sp_pcontext *dst_ctx)
   {}
 
-  /*
+  /**
     Mark this instruction as reachable during optimization and return the
     index to the next instruction. Jump instruction will add their
     destination to the leads list.
@@ -610,7 +617,7 @@ public:
     return m_ip+1;
   }
 
-  /*
+  /**
     Short-cut jumps to jumps during optimization. This is used by the
     jump instructions' opt_mark() methods. 'start' is the starting point,
     used to prevent the mark sweep from looping for ever. Return the
@@ -621,7 +628,7 @@ public:
     return m_ip;
   }
 
-  /*
+  /**
     Inform the instruction that it has been moved during optimization.
     Most instructions will simply update its index, but jump instructions
     must also take care of their destination pointers. Forward jumps get
@@ -635,7 +642,7 @@ public:
 }; // class sp_instr : public Sql_alloc
 
 
-/*
+/**
   Auxilary class to which instructions delegate responsibility
   for handling LEX and preparations before executing statement
   or calculating complex expression.
@@ -643,13 +650,14 @@ public:
   Exist mainly to avoid having double hierarchy between instruction
   classes.
 
-  TODO: Add ability to not store LEX and do any preparations if
-        expression used is simple.
+  @todo
+    Add ability to not store LEX and do any preparations if
+    expression used is simple.
 */
 
 class sp_lex_keeper
 {
-  /* Prevent use of these */
+  /** Prevent use of these */
   sp_lex_keeper(const sp_lex_keeper &);
   void operator=(sp_lex_keeper &);
 public:
@@ -669,10 +677,12 @@ public:
     }
   }
 
-  /*
+  /**
     Prepare execution of instruction using LEX, if requested check whenever
     we have read access to tables used and open/lock them, call instruction's
     exec_core() method, perform cleanup afterwards.
+   
+    @todo Conflicting comment in sp_head.cc
   */
   int reset_lex_and_exec_core(THD *thd, uint *nextp, bool open_tables,
                               sp_instr* instr);
@@ -689,7 +699,7 @@ public:
 private:
 
   LEX *m_lex;
-  /*
+  /**
     Indicates whenever this sp_lex_keeper instance responsible
     for LEX deletion.
   */
@@ -702,13 +712,13 @@ private:
        prelocked mode itself.
   */
   
-  /*
+  /**
     List of additional tables this statement needs to lock when it
     enters/leaves prelocked mode on its own.
   */
   TABLE_LIST *prelocking_tables;
 
-  /*
+  /**
     The value m_lex->query_tables_own_last should be set to this when the
     statement enters/leaves prelocked mode on its own.
   */
@@ -716,17 +726,17 @@ private:
 };
 
 
-//
-// Call out to some prepared SQL statement.
-//
+/**
+  Call out to some prepared SQL statement.
+*/
 class sp_instr_stmt : public sp_instr
 {
-  sp_instr_stmt(const sp_instr_stmt &);	/* Prevent use of these */
+  sp_instr_stmt(const sp_instr_stmt &);	/**< Prevent use of these */
   void operator=(sp_instr_stmt &);
 
 public:
 
-  LEX_STRING m_query;		// For thd->query
+  LEX_STRING m_query;		///< For thd->query
 
   sp_instr_stmt(uint ip, sp_pcontext *ctx, LEX *lex)
     : sp_instr(ip, ctx), m_lex_keeper(lex, TRUE)
@@ -753,7 +763,7 @@ private:
 
 class sp_instr_set : public sp_instr
 {
-  sp_instr_set(const sp_instr_set &);	/* Prevent use of these */
+  sp_instr_set(const sp_instr_set &);	/**< Prevent use of these */
   void operator=(sp_instr_set &);
 
 public:
@@ -776,15 +786,15 @@ public:
 
 private:
 
-  uint m_offset;		// Frame offset
+  uint m_offset;		///< Frame offset
   Item *m_value;
-  enum enum_field_types m_type;	// The declared type
+  enum enum_field_types m_type;	///< The declared type
   sp_lex_keeper m_lex_keeper;
 
 }; // class sp_instr_set : public sp_instr
 
 
-/*
+/**
   Set NEW/OLD row field value instruction. Used in triggers.
 */
 class sp_instr_set_trigger_field : public sp_instr
@@ -818,18 +828,19 @@ private:
 }; // class sp_instr_trigger_field : public sp_instr
 
 
-/*
+/**
   An abstract class for all instructions with destinations that
   needs to be updated by the optimizer.
+
   Even if not all subclasses will use both the normal destination and
   the continuation destination, we put them both here for simplicity.
- */
+*/
 class sp_instr_opt_meta : public sp_instr
 {
 public:
 
-  uint m_dest;			// Where we will go
-  uint m_cont_dest;             // Where continue handlers will go
+  uint m_dest;			///< Where we will go
+  uint m_cont_dest;             ///< Where continue handlers will go
 
   sp_instr_opt_meta(uint ip, sp_pcontext *ctx)
     : sp_instr(ip, ctx),
@@ -851,14 +862,14 @@ public:
 
 protected:
 
-  sp_instr *m_optdest;		// Used during optimization
-  sp_instr *m_cont_optdest;     // Used during optimization
+  sp_instr *m_optdest;		///< Used during optimization
+  sp_instr *m_cont_optdest;     ///< Used during optimization
 
 }; // class sp_instr_opt_meta : public sp_instr
 
 class sp_instr_jump : public sp_instr_opt_meta
 {
-  sp_instr_jump(const sp_instr_jump &);	/* Prevent use of these */
+  sp_instr_jump(const sp_instr_jump &);	/**< Prevent use of these */
   void operator=(sp_instr_jump &);
 
 public:
@@ -890,7 +901,7 @@ public:
       m_dest= dest;
   }
 
-  /*
+  /**
     Update the destination; used by the optimizer.
   */
   virtual void set_destination(uint old_dest, uint new_dest)
@@ -904,7 +915,7 @@ public:
 
 class sp_instr_jump_if_not : public sp_instr_jump
 {
-  sp_instr_jump_if_not(const sp_instr_jump_if_not &); /* Prevent use of these */
+  sp_instr_jump_if_not(const sp_instr_jump_if_not &); /**< Prevent use of these */
   void operator=(sp_instr_jump_if_not &);
 
 public:
@@ -930,7 +941,7 @@ public:
 
   virtual uint opt_mark(sp_head *sp, List<sp_instr> *leads);
 
-  /* Override sp_instr_jump's shortcut; we stop here */
+  /** Override sp_instr_jump's shortcut; we stop here */
   virtual uint opt_shortcut_jump(sp_head *sp, sp_instr *start)
   {
     return m_ip;
@@ -947,7 +958,7 @@ public:
 
 private:
 
-  Item *m_expr;			// The condition
+  Item *m_expr;			///< The condition
   sp_lex_keeper m_lex_keeper;
 
 }; // class sp_instr_jump_if_not : public sp_instr_jump
@@ -955,7 +966,7 @@ private:
 
 class sp_instr_freturn : public sp_instr
 {
-  sp_instr_freturn(const sp_instr_freturn &);	/* Prevent use of these */
+  sp_instr_freturn(const sp_instr_freturn &);	/**< Prevent use of these */
   void operator=(sp_instr_freturn &);
 
 public:
@@ -992,7 +1003,7 @@ protected:
 
 class sp_instr_hpush_jump : public sp_instr_jump
 {
-  sp_instr_hpush_jump(const sp_instr_hpush_jump &); /* Prevent use of these */
+  sp_instr_hpush_jump(const sp_instr_hpush_jump &); /**< Prevent use of these */
   void operator=(sp_instr_hpush_jump &);
 
 public:
@@ -1014,7 +1025,7 @@ public:
 
   virtual uint opt_mark(sp_head *sp, List<sp_instr> *leads);
 
-  /* Override sp_instr_jump's shortcut; we stop here. */
+  /** Override sp_instr_jump's shortcut; we stop here. */
   virtual uint opt_shortcut_jump(sp_head *sp, sp_instr *start)
   {
     return m_ip;
@@ -1027,7 +1038,7 @@ public:
 
 private:
 
-  int m_type;			// Handler type
+  int m_type;			///< Handler type
   uint m_frame;
   List<struct sp_cond_type> m_cond;
 
@@ -1036,7 +1047,7 @@ private:
 
 class sp_instr_hpop : public sp_instr
 {
-  sp_instr_hpop(const sp_instr_hpop &);	/* Prevent use of these */
+  sp_instr_hpop(const sp_instr_hpop &);	/**< Prevent use of these */
   void operator=(sp_instr_hpop &);
 
 public:
@@ -1061,7 +1072,7 @@ private:
 
 class sp_instr_hreturn : public sp_instr_jump
 {
-  sp_instr_hreturn(const sp_instr_hreturn &);	/* Prevent use of these */
+  sp_instr_hreturn(const sp_instr_hreturn &);	/**< Prevent use of these */
   void operator=(sp_instr_hreturn &);
 
 public:
@@ -1092,10 +1103,10 @@ private:
 }; // class sp_instr_hreturn : public sp_instr_jump
 
 
-/* This is DECLARE CURSOR */
+/** This is DECLARE CURSOR */
 class sp_instr_cpush : public sp_instr
 {
-  sp_instr_cpush(const sp_instr_cpush &); /* Prevent use of these */
+  sp_instr_cpush(const sp_instr_cpush &); /**< Prevent use of these */
   void operator=(sp_instr_cpush &);
 
 public:
@@ -1111,7 +1122,7 @@ public:
 
   virtual void print(String *str);
 
-  /*
+  /**
     This call is used to cleanup the instruction when a sensitive
     cursor is closed. For now stored procedures always use materialized
     cursors and the call is not used.
@@ -1120,14 +1131,14 @@ public:
 private:
 
   sp_lex_keeper m_lex_keeper;
-  uint m_cursor;                /* Frame offset (for debugging) */
+  uint m_cursor;                /**< Frame offset (for debugging) */
 
 }; // class sp_instr_cpush : public sp_instr
 
 
 class sp_instr_cpop : public sp_instr
 {
-  sp_instr_cpop(const sp_instr_cpop &); /* Prevent use of these */
+  sp_instr_cpop(const sp_instr_cpop &); /**< Prevent use of these */
   void operator=(sp_instr_cpop &);
 
 public:
@@ -1152,7 +1163,7 @@ private:
 
 class sp_instr_copen : public sp_instr
 {
-  sp_instr_copen(const sp_instr_copen &); /* Prevent use of these */
+  sp_instr_copen(const sp_instr_copen &); /**< Prevent use of these */
   void operator=(sp_instr_copen &);
 
 public:
@@ -1172,14 +1183,14 @@ public:
 
 private:
 
-  uint m_cursor;		// Stack index
+  uint m_cursor;		///< Stack index
 
 }; // class sp_instr_copen : public sp_instr_stmt
 
 
 class sp_instr_cclose : public sp_instr
 {
-  sp_instr_cclose(const sp_instr_cclose &); /* Prevent use of these */
+  sp_instr_cclose(const sp_instr_cclose &); /**< Prevent use of these */
   void operator=(sp_instr_cclose &);
 
 public:
@@ -1204,7 +1215,7 @@ private:
 
 class sp_instr_cfetch : public sp_instr
 {
-  sp_instr_cfetch(const sp_instr_cfetch &); /* Prevent use of these */
+  sp_instr_cfetch(const sp_instr_cfetch &); /**< Prevent use of these */
   void operator=(sp_instr_cfetch &);
 
 public:
@@ -1237,7 +1248,7 @@ private:
 
 class sp_instr_error : public sp_instr
 {
-  sp_instr_error(const sp_instr_error &); /* Prevent use of these */
+  sp_instr_error(const sp_instr_error &); /**< Prevent use of these */
   void operator=(sp_instr_error &);
 
 public:
diff --git a/sql/sql_cache.h b/sql/sql_cache.h
index b47e2e9a43b..f2c33eff614 100644
--- a/sql/sql_cache.h
+++ b/sql/sql_cache.h
@@ -66,8 +66,8 @@ struct Query_cache_result;
 class Query_cache;
 
 /**
-  @brief This class represents a node in the linked chain of queries
-         belonging to one table.
+  This class represents a node in the linked chain of queries
+  belonging to one table.
 
   @note The root of this linked list is not a query-type block, but the table-
         type block which all queries has in common.
diff --git a/sql/sql_class.h b/sql/sql_class.h
index 7875870bd1a..e8bfab370a9 100644
--- a/sql/sql_class.h
+++ b/sql/sql_class.h
@@ -77,10 +77,10 @@ typedef struct st_user_var_events
       was actually changed or not.
 */
 typedef struct st_copy_info {
-  ha_rows records; /* Number of processed records */
-  ha_rows deleted; /* Number of deleted records */
-  ha_rows updated; /* Number of updated records */
-  ha_rows copied;  /* Number of copied records */
+  ha_rows records; /**< Number of processed records */
+  ha_rows deleted; /**< Number of deleted records */
+  ha_rows updated; /**< Number of updated records */
+  ha_rows copied;  /**< Number of copied records */
   ha_rows error_count;
   ha_rows touched; /* Number of touched records */
   enum enum_duplicates handle_duplicates;
@@ -1045,14 +1045,17 @@ public:
   */
   char *catalog;
 
-  /*
-    WARNING: some members of THD (currently 'Statement::db',
+  /**
+    @note
+    Some members of THD (currently 'Statement::db',
     'catalog' and 'query')  are set and alloced by the slave SQL thread
     (for the THD of that thread); that thread is (and must remain, for now)
     the only responsible for freeing these 3 members. If you add members
     here, and you add code to set them in replication, don't forget to
     free_them_and_set_them_to_0 in replication properly. For details see
     the 'err:' label of the handle_slave_sql() in sql/slave.cc.
+
+    @see handle_slave_sql
   */
 
   Security_context main_security_ctx;
diff --git a/sql/sql_cursor.h b/sql/sql_cursor.h
index 6edd6b24b36..1f19cbfdbcf 100644
--- a/sql/sql_cursor.h
+++ b/sql/sql_cursor.h
@@ -20,12 +20,14 @@
 #pragma interface                              /* gcc class interface */
 #endif
 
-/*
+/**
+  @file
+
   Declarations for implementation of server side cursors. Only
   read-only non-scrollable cursors are currently implemented.
 */
 
-/*
+/**
   Server_side_cursor -- an interface for materialized and
   sensitive (non-materialized) implementation of cursors. All
   cursors are self-contained (created in their own memory root).
@@ -36,7 +38,7 @@
 class Server_side_cursor: protected Query_arena, public Sql_alloc
 {
 protected:
-  /* Row destination used for fetch */
+  /** Row destination used for fetch */
   select_result *result;
 public:
   Server_side_cursor(MEM_ROOT *mem_root_arg, select_result *result_arg)
@@ -58,8 +60,7 @@ int mysql_open_cursor(THD *thd, uint flags,
                       select_result *result,
                       Server_side_cursor **res);
 
-/* Possible values for flags */
-
+/** Possible values for flags */
 enum { ANY_CURSOR= 1, ALWAYS_MATERIALIZED_CURSOR= 2 };
 
 #endif /* _sql_cusor_h_ */
diff --git a/sql/sql_select.h b/sql/sql_select.h
index efa92432e2b..f91a965d4ac 100644
--- a/sql/sql_select.h
+++ b/sql/sql_select.h
@@ -14,7 +14,12 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* classes to use when handling where clause */
+/**
+  @file
+
+  @brief
+  classes to use when handling where clause
+*/
 
 #ifdef USE_PRAGMA_INTERFACE
 #pragma interface			/* gcc class implementation */
@@ -25,12 +30,12 @@
 
 typedef struct keyuse_t {
   TABLE *table;
-  Item	*val;				/* or value if no field */
+  Item	*val;				/**< or value if no field */
   table_map used_tables;
   uint	key, keypart, optimize;
   key_part_map keypart_map;
   ha_rows      ref_table_rows;
-  /* 
+  /**
     If true, the comparison this value was created from will not be
     satisfied if val has NULL 'value'.
   */
@@ -53,13 +58,13 @@ class store_key;
 typedef struct st_table_ref
 {
   bool		key_err;
-  uint          key_parts;                // num of ...
-  uint          key_length;               // length of key_buff
-  int           key;                      // key no
-  uchar         *key_buff;                // value to look for with key
-  uchar         *key_buff2;               // key_buff+key_length
+  uint          key_parts;                ///< num of ...
+  uint          key_length;               ///< length of key_buff
+  int           key;                      ///< key no
+  uchar         *key_buff;                ///< value to look for with key
+  uchar         *key_buff2;               ///< key_buff+key_length
   store_key     **key_copy;               //
-  Item          **items;                  // val()'s for each keypart
+  Item          **items;                  ///< val()'s for each keypart
   /*  
     Array of pointers to trigger variables. Some/all of the pointers may be
     NULL.  The ref access can be used iff
@@ -72,18 +77,18 @@ typedef struct st_table_ref
     underlying conditions is switched off (see subquery code for more details)
   */
   bool          **cond_guards;
-  /*
+  /**
     (null_rejecting & (1<<i)) means the condition is '=' and no matching
     rows will be produced if items[i] IS NULL (see add_not_null_conds())
   */
   key_part_map  null_rejecting;
-  table_map	depend_map;		  // Table depends on these tables.
+  table_map	depend_map;		  ///< Table depends on these tables.
   /* null byte position in the key_buf. Used for REF_OR_NULL optimization */
   uchar          *null_ref_key;
 } TABLE_REF;
 
 
-/*
+/**
   CACHE_FIELD and JOIN_CACHE is used on full join to cache records in outer
   table
 */
@@ -136,18 +141,18 @@ Next_select_func setup_end_select_func(JOIN *join);
 typedef struct st_join_table {
   st_join_table() {}                          /* Remove gcc warning */
   TABLE		*table;
-  KEYUSE	*keyuse;			/* pointer to first used key */
+  KEYUSE	*keyuse;			/**< pointer to first used key */
   SQL_SELECT	*select;
   COND		*select_cond;
   QUICK_SELECT_I *quick;
-  Item	       **on_expr_ref;   /* pointer to the associated on expression   */
-  COND_EQUAL    *cond_equal;    /* multiple equalities for the on expression */
-  st_join_table *first_inner;   /* first inner table for including outerjoin */
-  bool           found;         /* true after all matches or null complement */
-  bool           not_null_compl;/* true before null complement is added      */
-  st_join_table *last_inner;    /* last table table for embedding outer join */
-  st_join_table *first_upper;  /* first inner table for embedding outer join */
-  st_join_table *first_unmatched; /* used for optimization purposes only     */
+  Item	       **on_expr_ref;   /**< pointer to the associated on expression   */
+  COND_EQUAL    *cond_equal;    /**< multiple equalities for the on expression */
+  st_join_table *first_inner;   /**< first inner table for including outerjoin */
+  bool           found;         /**< true after all matches or null complement */
+  bool           not_null_compl;/**< true before null complement is added      */
+  st_join_table *last_inner;    /**< last table table for embedding outer join */
+  st_join_table *first_upper;  /**< first inner table for embedding outer join */
+  st_join_table *first_unmatched; /**< used for optimization purposes only     */
   
   /* Special content for EXPLAIN 'Extra' column or NULL if none */
   const char	*info;
@@ -168,10 +173,10 @@ typedef struct st_join_table {
   Read_record_func save_read_first_record;/* to save read_first_record */ 
   int (*save_read_record) (READ_RECORD *);/* to save read_record.read_record */
   double	worst_seeks;
-  key_map	const_keys;			/* Keys with constant part */
-  key_map	checked_keys;			/* Keys checked in find_best */
+  key_map	const_keys;			/**< Keys with constant part */
+  key_map	checked_keys;			/**< Keys checked in find_best */
   key_map	needed_reg;
-  key_map       keys;                           /* all keys with can be used */
+  key_map       keys;                           /**< all keys with can be used */
 
   /* Either #rows in the table or 1 for const table.  */
   ha_rows	records;
@@ -189,7 +194,7 @@ typedef struct st_join_table {
   
   table_map	dependent,key_dependent;
   uint		use_quick,index;
-  uint		status;				// Save status for cache
+  uint		status;				///< Save status for cache
   uint		used_fields,used_fieldlength,used_blobs;
   enum join_type type;
   bool		cached_eq_ref_table,eq_ref_table,not_used_in_distinct;
@@ -203,7 +208,7 @@ typedef struct st_join_table {
   TABLE_REF	ref;
   JOIN_CACHE	cache;
   JOIN		*join;
-  /* Bitmap of nested joins this table is part of */
+  /** Bitmap of nested joins this table is part of */
   nested_join_map embedding_map;
 
   void cleanup();
@@ -220,7 +225,7 @@ enum_nested_loop_state sub_select_cache(JOIN *join, JOIN_TAB *join_tab, bool
 enum_nested_loop_state sub_select(JOIN *join,JOIN_TAB *join_tab, bool
                                   end_of_records);
 
-/*
+/**
   Information about a position of table within a join order. Used in join
   optimization.
 */
@@ -264,25 +269,25 @@ typedef struct st_rollup
 
 class JOIN :public Sql_alloc
 {
-  JOIN(const JOIN &rhs);                        /* not implemented */
-  JOIN& operator=(const JOIN &rhs);             /* not implemented */
+  JOIN(const JOIN &rhs);                        /**< not implemented */
+  JOIN& operator=(const JOIN &rhs);             /**< not implemented */
 public:
   JOIN_TAB *join_tab,**best_ref;
-  JOIN_TAB **map2table;    // mapping between table indexes and JOIN_TABs
-  JOIN_TAB *join_tab_save; // saved join_tab for subquery reexecution
+  JOIN_TAB **map2table;    ///< mapping between table indexes and JOIN_TABs
+  JOIN_TAB *join_tab_save; ///< saved join_tab for subquery reexecution
   TABLE    **table,**all_tables,*sort_by_table;
   uint	   tables,const_tables;
   uint	   send_group_parts;
   bool	   sort_and_group,first_record,full_join,group, no_field_update;
   bool	   do_send_rows;
-  /*
+  /**
     TRUE when we want to resume nested loop iterations when
     fetching data from a cursor
   */
   bool     resume_nested_loop;
   table_map const_table_map,found_const_table_map,outer_join;
   ha_rows  send_records,found_records,examined_rows,row_limit, select_limit;
-  /*
+  /**
     Used to fetch no more than given amount of rows per one
     fetch operation of server side cursor.
     The value is checked in end_send and end_send_group in fashion, similar
@@ -294,7 +299,7 @@ public:
   ha_rows  fetch_limit;
   POSITION positions[MAX_TABLES+1],best_positions[MAX_TABLES+1];
   
-  /* 
+  /* *
     Bitmap of nested joins embedding the position at the end of the current 
     partial join (valid only during join optimizer run).
   */
@@ -304,25 +309,25 @@ public:
   List<Item> *fields;
   List<Cached_item> group_fields, group_fields_cache;
   TABLE    *tmp_table;
-  // used to store 2 possible tmp table of SELECT
+  /// used to store 2 possible tmp table of SELECT
   TABLE    *exec_tmp_table1, *exec_tmp_table2;
   THD	   *thd;
   Item_sum  **sum_funcs, ***sum_funcs_end;
-  /* second copy of sumfuncs (for queries with 2 temporary tables */
+  /** second copy of sumfuncs (for queries with 2 temporary tables */
   Item_sum  **sum_funcs2, ***sum_funcs_end2;
   Procedure *procedure;
   Item	    *having;
-  Item      *tmp_having; // To store having when processed temporary table
-  Item      *having_history; // Store having for explain
+  Item      *tmp_having; ///< To store having when processed temporary table
+  Item      *having_history; ///< Store having for explain
   ulonglong  select_options;
   select_result *result;
   TMP_TABLE_PARAM tmp_table_param;
   MYSQL_LOCK *lock;
-  // unit structure (with global parameters) for this select
+  /// unit structure (with global parameters) for this select
   SELECT_LEX_UNIT *unit;
-  // select that processed
+  /// select that processed
   SELECT_LEX *select_lex;
-  /* 
+  /** 
     TRUE <=> optimizer must not mark any table as a constant table.
     This is needed for subqueries in form "a IN (SELECT .. UNION SELECT ..):
     when we optimize the select that reads the results of the union from a
@@ -331,11 +336,11 @@ public:
   */
   bool no_const_tables; 
   
-  JOIN *tmp_join; // copy of this JOIN to be used with temporary tables
-  ROLLUP rollup;				// Used with rollup
+  JOIN *tmp_join; ///< copy of this JOIN to be used with temporary tables
+  ROLLUP rollup;				///< Used with rollup
 
-  bool select_distinct;				// Set if SELECT DISTINCT
-  /*
+  bool select_distinct;				///< Set if SELECT DISTINCT
+  /**
     If we have the GROUP BY statement in the query,
     but the group_list was emptied by optimizer, this
     flag is TRUE.
@@ -350,42 +355,42 @@ public:
     It's also set if ORDER/GROUP BY is empty.
   */
   bool simple_order, simple_group;
-  /*
+  /**
     Is set only in case if we have a GROUP BY clause
     and no ORDER BY after constant elimination of 'order'.
   */
   bool no_order;
-  /* Is set if we have a GROUP BY and we have ORDER BY on a constant. */
+  /** Is set if we have a GROUP BY and we have ORDER BY on a constant. */
   bool          skip_sort_order;
 
   bool need_tmp, hidden_group_fields;
   DYNAMIC_ARRAY keyuse;
   Item::cond_result cond_value, having_value;
-  List<Item> all_fields; // to store all fields that used in query
-  //Above list changed to use temporary table
+  List<Item> all_fields; ///< to store all fields that used in query
+  ///Above list changed to use temporary table
   List<Item> tmp_all_fields1, tmp_all_fields2, tmp_all_fields3;
-  //Part, shared with list above, emulate following list
+  ///Part, shared with list above, emulate following list
   List<Item> tmp_fields_list1, tmp_fields_list2, tmp_fields_list3;
-  List<Item> &fields_list; // hold field list passed to mysql_select
+  List<Item> &fields_list; ///< hold field list passed to mysql_select
   List<Item> procedure_fields_list;
   int error;
 
   ORDER *order, *group_list, *proc_param; //hold parameters of mysql_select
   COND *conds;                            // ---"---
   Item *conds_history;                    // store WHERE for explain
-  TABLE_LIST *tables_list;           //hold 'tables' parameter of mysql_select
-  List<TABLE_LIST> *join_list;       // list of joined tables in reverse order
+  TABLE_LIST *tables_list;           ///<hold 'tables' parameter of mysql_select
+  List<TABLE_LIST> *join_list;       ///< list of joined tables in reverse order
   COND_EQUAL *cond_equal;
-  SQL_SELECT *select;                //created in optimisation phase
-  JOIN_TAB *return_tab;              //used only for outer joins
-  Item **ref_pointer_array; //used pointer reference for this select
+  SQL_SELECT *select;                ///<created in optimisation phase
+  JOIN_TAB *return_tab;              ///<used only for outer joins
+  Item **ref_pointer_array; ///<used pointer reference for this select
   // Copy of above to be used with different lists
   Item **items0, **items1, **items2, **items3, **current_ref_pointer_array;
-  uint ref_pointer_array_size; // size of above in bytes
-  const char *zero_result_cause; // not 0 if exec must return zero result
+  uint ref_pointer_array_size; ///< size of above in bytes
+  const char *zero_result_cause; ///< not 0 if exec must return zero result
   
-  bool union_part; // this subselect is part of union 
-  bool optimized; // flag to avoid double optimization in EXPLAIN
+  bool union_part; ///< this subselect is part of union 
+  bool optimized; ///< flag to avoid double optimization in EXPLAIN
 
   /* 
     storage for caching buffers allocated during query execution. 
@@ -494,14 +499,14 @@ public:
   int rollup_send_data(uint idx);
   int rollup_write_data(uint idx, TABLE *table);
   void remove_subq_pushed_predicates(Item **where);
-  /*
+  /**
     Release memory and, if possible, the open tables held by this execution
     plan (and nested plans). It's used to release some tables before
     the end of execution in order to increase concurrency and reduce
     memory consumption.
   */
   void join_free();
-  /* Cleanup this JOIN, possibly for reuse */
+  /** Cleanup this JOIN, possibly for reuse */
   void cleanup(bool full);
   void clear();
   bool save_join_tab();
@@ -556,7 +561,7 @@ int opt_sum_query(TABLE_LIST *tables, List<Item> &all_fields,COND *conds);
 /* from sql_delete.cc, used by opt_range.cc */
 extern "C" int refpos_order_cmp(void* arg, const void *a,const void *b);
 
-/* class to copying an field/item to a key struct */
+/** class to copying an field/item to a key struct */
 
 class store_key :public Sql_alloc
 {
@@ -578,7 +583,7 @@ public:
       to_field=field_arg->new_key_field(thd->mem_root, field_arg->table,
                                         ptr, null, 1);
   }
-  virtual ~store_key() {}			/* Not actually needed */
+  virtual ~store_key() {}			/** Not actually needed */
   virtual const char *name() const=0;
 
   /**
diff --git a/sql/sql_trigger.h b/sql/sql_trigger.h
index 8f6b08c927f..1b0edf6bea8 100644
--- a/sql/sql_trigger.h
+++ b/sql/sql_trigger.h
@@ -14,7 +14,7 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA */
 
 
-/*
+/**
   This class holds all information about triggers of table.
 
   QQ: Will it be merged into TABLE in the future ?
@@ -22,20 +22,20 @@
 
 class Table_triggers_list: public Sql_alloc
 {
-  /* Triggers as SPs grouped by event, action_time */
+  /** Triggers as SPs grouped by event, action_time */
   sp_head *bodies[TRG_EVENT_MAX][TRG_ACTION_MAX];
-  /*
+  /**
     Heads of the lists linking items for all fields used in triggers
     grouped by event and action_time.
   */
   Item_trigger_field *trigger_fields[TRG_EVENT_MAX][TRG_ACTION_MAX];
-  /*
+  /**
     Copy of TABLE::Field array with field pointers set to TABLE::record[1]
     buffer instead of TABLE::record[0] (used for OLD values in on UPDATE
     trigger and DELETE trigger when it is called for REPLACE).
   */
   Field             **record1_field;
-  /*
+  /**
     During execution of trigger new_field and old_field should point to the
     array of fields representing new or old version of row correspondingly
     (so it can point to TABLE::field or to Tale_triggers_list::record1_field)
@@ -45,30 +45,30 @@ class Table_triggers_list: public Sql_alloc
 
   /* TABLE instance for which this triggers list object was created */
   TABLE *trigger_table;
-  /*
+  /**
     Names of triggers.
     Should correspond to order of triggers on definitions_list,
     used in CREATE/DROP TRIGGER for looking up trigger by name.
   */
   List<LEX_STRING>  names_list;
-  /*
+  /**
     List of "ON table_name" parts in trigger definitions, used for
     updating trigger definitions during RENAME TABLE.
   */
   List<LEX_STRING>  on_table_names_list;
 
-  /*
+  /**
     Grant information for each trigger (pair: subject table, trigger definer).
   */
   GRANT_INFO        subject_table_grants[TRG_EVENT_MAX][TRG_ACTION_MAX];
 
 public:
-  /*
+  /**
     Field responsible for storing triggers definitions in file.
     It have to be public because we are using it directly from parser.
   */
   List<LEX_STRING>  definitions_list;
-  /*
+  /**
     List of sql modes for triggers
   */
   List<ulonglong> definition_modes_list;
diff --git a/sql/structs.h b/sql/structs.h
index 09a3c4d7285..aeaa3a31005 100644
--- a/sql/structs.h
+++ b/sql/structs.h
@@ -209,7 +209,7 @@ typedef struct  user_conn {
   char *user;
   /* Pointer to host part of the key. */
   char *host;
-  /*
+  /**
      The moment of time when per hour counters were reset last time
      (i.e. start of "hour" for conn_per_hour, updates, questions counters).
   */
diff --git a/sql/tztime.h b/sql/tztime.h
index ddd80b88bf2..3d77a3eefa3 100644
--- a/sql/tztime.h
+++ b/sql/tztime.h
@@ -20,7 +20,7 @@
 
 #if !defined(TESTTIME) && !defined(TZINFO2SQL)
 
-/*
+/**
   This class represents abstract time zone and provides 
   basic interface for MYSQL_TIME <-> my_time_t conversion.
   Actual time zones which are specified by DB, or via offset 
@@ -30,7 +30,7 @@ class Time_zone: public Sql_alloc
 {
 public:
   Time_zone() {}                              /* Remove gcc warning */
-  /*
+  /**
     Converts local time in broken down MYSQL_TIME representation to 
     my_time_t (UTC seconds since Epoch) represenation.
     Returns 0 in case of error. Sets in_dst_time_gap to true if date provided
@@ -38,19 +38,19 @@ public:
   */
   virtual my_time_t TIME_to_gmt_sec(const MYSQL_TIME *t, 
                                     my_bool *in_dst_time_gap) const = 0;
-  /*
+  /**
     Converts time in my_time_t representation to local time in
     broken down MYSQL_TIME representation.
   */
   virtual void   gmt_sec_to_TIME(MYSQL_TIME *tmp, my_time_t t) const = 0;
-  /*
+  /**
     Because of constness of String returned by get_name() time zone name 
     have to be already zeroended to be able to use String::ptr() instead
     of c_ptr().
   */
   virtual const String * get_name() const = 0;
 
-  /* 
+  /** 
     We need this only for surpressing warnings, objects of this type are
     allocated on MEM_ROOT and should not require destruction.
   */
@@ -65,7 +65,7 @@ extern my_bool     my_tz_init(THD *org_thd, const char *default_tzname, my_bool
 extern void        my_tz_free();
 extern my_time_t   sec_since_epoch_TIME(MYSQL_TIME *t);
 
-/*
+/**
   Number of elements in table list produced by my_tz_get_table_list()
   (this table list contains tables which are needed for dynamical loading
   of time zone descriptions). Actually it is imlementation detail that
diff --git a/sql/unireg.h b/sql/unireg.h
index f0b4a88c7f8..2e0172ce31d 100644
--- a/sql/unireg.h
+++ b/sql/unireg.h
@@ -155,34 +155,34 @@
 #define OPEN_VIEW		8192	/* Allow open on view */
 #define OPEN_VIEW_NO_PARSE     16384    /* Open frm only if it's a view,
                                            but do not parse view itself */
-/*
+/**
   This flag is used in function get_all_tables() which fills
   I_S tables with data which are retrieved from frm files and storage engine
   The flag means that we need to open FRM file only to get necessary data.
 */
 #define OPEN_FRM_FILE_ONLY     32768
-/*
+/**
   This flag is used in function get_all_tables() which fills
   I_S tables with data which are retrieved from frm files and storage engine
   The flag means that we need to process tables only to get necessary data.
   Views are not processed.
 */
 #define OPEN_TABLE_ONLY        OPEN_FRM_FILE_ONLY*2
-/*
+/**
   This flag is used in function get_all_tables() which fills
   I_S tables with data which are retrieved from frm files and storage engine
   The flag means that we need to process views only to get necessary data.
   Tables are not processed.
 */
 #define OPEN_VIEW_ONLY         OPEN_TABLE_ONLY*2
-/*
+/**
   This flag is used in function get_all_tables() which fills
   I_S tables with data which are retrieved from frm files and storage engine.
   The flag means that we need to open a view using
   open_normal_and_derived_tables() function.
 */
 #define OPEN_VIEW_FULL         OPEN_VIEW_ONLY*2
-/*
+/**
   This flag is used in function get_all_tables() which fills
   I_S tables with data which are retrieved from frm files and storage engine.
   The flag means that I_S table uses optimization algorithm.