Doxygenized comments.

sql/sql_base.cc

@@ -1817,7 +1817,7 @@ static void relink_unused(TABLE *table)
 
 
 /**
-    @brief  Remove all instances of table from thread's open list and
+    Remove all instances of table from thread's open list and
     table cache.
 
     @param  thd     Thread context
@@ -1867,7 +1867,7 @@ void unlink_open_table(THD *thd, TABLE *find, bool unlock)
 
 
 /**
-    @brief Auxiliary routine which closes and drops open table.
+    Auxiliary routine which closes and drops open table.
 
     @param  thd         Thread handle
     @param  table       TABLE object for table to be dropped
@@ -2039,7 +2039,7 @@ bool reopen_name_locked_table(THD* thd, TABLE_LIST* table_list, bool link_in)
 
 
 /**
-    @brief Create and insert into table cache placeholder for table
+    Create and insert into table cache placeholder for table
     which will prevent its opening (or creation) (a.k.a lock
     table name).
 
@@ -2090,7 +2090,7 @@ TABLE *table_cache_insert_placeholder(THD *thd, const char *key,
 
 
 /**
-    @brief Obtain an exclusive name lock on the table if it is not cached
+    Obtain an exclusive name lock on the table if it is not cached
     in the table cache.
 
     @param      thd         Thread context
@@ -2142,7 +2142,7 @@ bool lock_table_name_if_not_cached(THD *thd, const char *db,
 
 
 /**
-    @brief Check that table exists in table definition cache, on disk
+    Check that table exists in table definition cache, on disk
     or in some storage engine.
 
     @param       thd     Thread context
@@ -2815,7 +2815,7 @@ bool reopen_table(TABLE *table)
 
 
 /**
-    @brief Close all instances of a table open by this thread and replace
+    Close all instances of a table open by this thread and replace
     them with exclusive name-locks.
 
     @param thd        Thread context
@@ -2867,7 +2867,7 @@ void close_data_files_and_morph_locks(THD *thd, const char *db,
 
 
 /**
-    @brief Reopen all tables with closed data files.
+    Reopen all tables with closed data files.
 
     @param thd         Thread context
     @param get_locks   Should we get locks after reopening tables ?
@@ -2957,7 +2957,7 @@ bool reopen_tables(THD *thd,bool get_locks,bool in_refresh)
 
 
 /**
-    @brief Close handlers for tables in list, but leave the TABLE structure
+    Close handlers for tables in list, but leave the TABLE structure
     intact so that we can re-open these quickly.
 
     @param thd           Thread context

sql/sql_cache.cc

@@ -1524,7 +1524,7 @@ void Query_cache::invalidate(THD *thd, const char *key, uint32  key_length,
 
 
 /**
-  @brief Synchronize the thread with any flushing operations.
+  Synchronize the thread with any flushing operations.
 
   This helper function is called whenever a thread needs to operate on the
   query cache structure (example: during invalidation). If a table flush is in
@@ -1565,7 +1565,7 @@ void Query_cache::wait_while_table_flush_is_in_progress(bool *interrupt)
 
 
 /**
-   @brief Remove all cached queries that uses the given database
+   Remove all cached queries that uses the given database.
 */
 
 void Query_cache::invalidate(char *db)
@@ -1675,7 +1675,7 @@ void Query_cache::flush()
 
 
 /**
-  @brief Rearrange the memory blocks and join result in cache in 1 block (if
+  Rearrange the memory blocks and join result in cache in 1 block (if
   result length > join_limit)
 
   @param[in] join_limit If the minimum length of a result block to be joined.
@@ -1946,7 +1946,7 @@ void Query_cache::make_disabled()
 
 /**
   @class Query_cache
-  @brief Free all resources allocated by the cache.
+  Free all resources allocated by the cache.
 
   This function frees all resources allocated by the cache.  You
   have to call init_cache() before using the cache again. This function
@@ -1970,7 +1970,7 @@ void Query_cache::free_cache()
 
 
 /**
-  @brief Flush the cache.
+  Flush the cache.
 
   This function will flush cache contents.  It assumes we have
   'structure_guard_mutex' locked. The function sets the m_cache_status flag and
@@ -2516,7 +2516,7 @@ Query_cache::invalidate_table_internal(THD *thd, uchar *key, uint32 key_length)
 }
 
 /**
-  @brief Invalidate a linked list of query cache blocks.
+  Invalidate a linked list of query cache blocks.
 
   Each block tries to aquire a block level lock before
   free_query is a called. This function will in turn affect
@@ -2684,7 +2684,7 @@ my_bool Query_cache::register_all_tables(Query_cache_block *block,
 
 
 /**
-  @brief Insert used table name into the cache.
+  Insert used table name into the cache.
 
   @return Error status
     @retval FALSE On error
@@ -3413,7 +3413,7 @@ my_bool Query_cache::ask_handler_allowance(THD *thd,
 
 
 /**
-  @brief Rearrange all memory blocks so that free memory joins at the
+  Rearrange all memory blocks so that free memory joins at the
   'bottom' of the allocated memory block containing all cache data.
   @see Query_cache::pack(ulong join_limit, uint iteration_limit)
 */
@@ -4028,7 +4028,7 @@ void Query_cache::tables_dump()
 
 
 /**
-  @brief Checks integrity of the various linked lists
+  Checks integrity of the various linked lists
 
   @return Error status code
     @retval FALSE Query cache is operational.

sql/sql_class.cc

@@ -934,7 +934,7 @@ void THD::cleanup_after_query()
 
 
 /**
-  Create a LEX_STRING in this connection
+  Create a LEX_STRING in this connection.
 
   @param lex_str  pointer to LEX_STRING object to be initialized
   @param str      initializer to be copied into lex_str

sql/sql_cursor.cc

@@ -24,9 +24,9 @@
   Declarations.
 ****************************************************************************/
 
-/*
+/**
   Sensitive_cursor -- a sensitive non-materialized server side
-  cursor An instance of this class cursor has its own runtime
+  cursor.  An instance of this class cursor has its own runtime
   state -- list of used items and memory root for runtime memory,
   open and locked tables, change list for the changes of the
   parsed tree. This state is freed when the cursor is closed.
@@ -69,7 +69,7 @@ class Sensitive_cursor: public Server_side_cursor
 };
 
 
-/*
+/**
   Materialized_cursor -- an insensitive materialized server-side
   cursor. The result set of this cursor is saved in a temporary
   table at open. The cursor itself is simply an interface for the
@@ -96,7 +96,7 @@ class Materialized_cursor: public Server_side_cursor
 };
 
 
-/*
+/**
   Select_materialize -- a mediator between a cursor query and the
   protocol. In case we were not able to open a non-materialzed
   cursor, it creates an internal temporary HEAP table, and insert
@@ -107,7 +107,7 @@ class Materialized_cursor: public Server_side_cursor
 
 class Select_materialize: public select_union
 {
-  select_result *result; /* the result object of the caller (PS or SP) */
+  select_result *result; /**< the result object of the caller (PS or SP) */
 public:
   Select_materialize(select_result *result_arg) :result(result_arg) {}
   virtual bool send_fields(List<Item> &list, uint flags);
@@ -116,21 +116,20 @@ class Select_materialize: public select_union
 
 /**************************************************************************/
 
-/*
+/**
   Attempt to open a materialized or non-materialized cursor.
 
-  SYNOPSIS
-    mysql_open_cursor()
-      thd                thread handle
-      flags   [in]       create a materialized cursor or not
-      result  [in]       result class of the caller used as a destination
+  @param      thd           thread handle
+  @param[in]  flags         create a materialized cursor or not
+  @param[in]  result        result class of the caller used as a destination
                             for the rows fetched from the cursor
-      pcursor [out]      a pointer to store a pointer to cursor in
+  @param[out] pcursor       a pointer to store a pointer to cursor in
 
-  RETURN VALUE
+  @retval
     0                 the query has been successfully executed; in this
     case pcursor may or may not contain
     a pointer to an open cursor.
+  @retval
     non-zero          an error, 'pcursor' has been left intact.
 */
 
@@ -279,6 +278,14 @@ Sensitive_cursor::Sensitive_cursor(THD *thd, select_result *result_arg)
 }
 
 
+/**
+  Save THD state into cursor.
+
+  @todo
+    - XXX: thd->locked_tables is not changed.
+    -  What problems can we have with it if cursor is open?
+    - TODO: must be fixed because of the prelocked mode.
+*/
 void
 Sensitive_cursor::post_open(THD *thd)
 {
@@ -334,6 +341,10 @@ Sensitive_cursor::post_open(THD *thd)
 }
 
 
+/**
+  bzero cursor state in THD.
+*/
+
 void
 Sensitive_cursor::reset_thd(THD *thd)
 {
@@ -393,20 +404,13 @@ Sensitive_cursor::open(JOIN *join_arg)
 }
 
 
-/*
-  SYNOPSIS
-    Sensitive_cursor::fetch()
-      num_rows           fetch up to this number of rows (maybe less)
-
-  DESCRIPTION
-    Fetch next num_rows rows from the cursor and send them to the client
+/**
+  Fetch next num_rows rows from the cursor and send them to the client.
 
   Precondition:
-    Sensitive_cursor is open
+  - Sensitive_cursor is open
 
-  RETURN VALUES:
-    none, this function will send OK to the clinet or set an error
-    message in THD
+  @param num_rows           fetch up to this number of rows (maybe less)
 */
 
 void
@@ -478,6 +482,11 @@ Sensitive_cursor::fetch(ulong num_rows)
 }
 
 
+/**
+  @todo
+  Another hack: we need to set THD state as if in a fetch to be
+  able to call stmt close.
+*/
 void
 Sensitive_cursor::close()
 {
@@ -579,10 +588,9 @@ int Materialized_cursor::open(JOIN *join __attribute__((unused)))
 }
 
 
-/*
+/**
   Fetch up to the given number of rows from a materialized cursor.
 
-  DESCRIPTION
     Precondition: the cursor is open.
 
     If the cursor points after the last row, the fetch will automatically
@@ -590,10 +598,6 @@ int Materialized_cursor::open(JOIN *join __attribute__((unused)))
     with SERVER_STATUS_LAST_ROW_SENT). This is an extra round trip
     and probably should be improved to return
     SERVER_STATUS_LAST_ROW_SENT along with the last row.
-
-  RETURN VALUE
-    none, in case of success the row is sent to the client, otherwise
-    an error message is set in THD
 */
 
 void Materialized_cursor::fetch(ulong num_rows)

sql/sql_parse.cc

@@ -158,8 +158,8 @@ bool begin_trans(THD *thd)
 }
 
 #ifdef HAVE_REPLICATION
-/*
-  Returns true if all tables should be ignored
+/**
+  Returns true if all tables should be ignored.
 */
 inline bool all_tables_not_ok(THD *thd, TABLE_LIST *tables)
 {
@@ -182,9 +182,10 @@ static bool some_non_temp_table_to_be_updated(THD *thd, TABLE_LIST *tables)
 }
 
 
-/*
-  Mark all commands that somehow changes a table
-  This is used to check number of updates / hour
+/**
+  Mark all commands that somehow changes a table.
+
+  This is used to check number of updates / hour.
 
   sql_command is actually set to SQLCOM_END sometimes
   so we need the +1 to include it in the array.
@@ -339,9 +340,10 @@ void execute_init_command(THD *thd, sys_var_str *init_command_var,
 }
 
 
-/*
+/**
   Execute commands from bootstrap_file.
-  Used when creating the initial grant tables
+
+  Used when creating the initial grant tables.
 */
 
 pthread_handler_t handle_bootstrap(void *arg)
@@ -495,21 +497,20 @@ void cleanup_items(Item *item)
   DBUG_VOID_RETURN;
 }
 
-/*
-  Handle COM_TABLE_DUMP command
+/**
+  Handle COM_TABLE_DUMP command.
 
-  SYNOPSIS
-    mysql_table_dump
-      thd           thread handle
-      db            database name or an empty string. If empty,
+  @param thd           thread handle
+  @param db            database name or an empty string. If empty,
                        the current database of the connection is used
-      tbl_name      name of the table to dump
+  @param tbl_name      name of the table to dump
 
-  NOTES
+  @note
     This function is written to handle one specific command only.
 
-  RETURN VALUE
+  @retval
     0               success
+  @retval
     1               error, the error message is set in THD
 */
 
@@ -563,16 +564,14 @@ int mysql_table_dump(THD *thd, LEX_STRING *db, char *tbl_name)
   DBUG_RETURN(error);
 }
 
-/*
-  Ends the current transaction and (maybe) begin the next
+/**
+  Ends the current transaction and (maybe) begin the next.
 
-  SYNOPSIS
-    end_trans()
-      thd            Current thread
-      completion     Completion type
+  @param thd            Current thread
+  @param completion     Completion type
 
-  RETURN
-    0 - OK
+  @retval
+    0   OK
 */
 
 int end_trans(THD *thd, enum enum_mysql_completiontype completion)
@@ -641,13 +640,12 @@ int end_trans(THD *thd, enum enum_mysql_completiontype completion)
 
 #ifndef EMBEDDED_LIBRARY
 
-/*
+/**
   Read one command from connection and execute it (query or simple command).
   This function is called in loop from thread function.
-  SYNOPSIS
-    do_command()
-  RETURN VALUE
+  @retval
     0  success
+  @retval
     1  request of thread shutdown (see dispatch_command() description)
 */
 
@@ -719,19 +717,23 @@ bool do_command(THD *thd)
 #endif  /* EMBEDDED_LIBRARY */
 
 
-/*
+/**
   Perform one connection-level (COM_XXXX) command.
 
-  SYNOPSIS
-    dispatch_command()
-    thd             connection handle
-    command         type of command to perform 
-    packet          data for the command, packet is always null-terminated
-    packet_length   length of packet + 1 (to show that data is
+  @param command         type of command to perform
+  @param thd             connection handle
+  @param packet          data for the command, packet is always null-terminated
+  @param packet_length   length of packet + 1 (to show that data is
                          null-terminated) except for COM_SLEEP, where it
                          can be zero.
-  RETURN VALUE
+
+  @todo
+    - TODO: set thd->lex->sql_command to SQLCOM_END here 
+    - TODO: The following has to be changed to an 8 byte integer
+
+  @retval
     0   ok
+  @retval
     1   request of thread shutdown, i. e. if command is
     COM_QUIT/COM_SHUTDOWN
 */
@@ -1380,30 +1382,28 @@ void log_slow_statement(THD *thd)
 }
 
 
-/*
+/**
   Create a TABLE_LIST object for an INFORMATION_SCHEMA table.
 
-  SYNOPSIS
-    prepare_schema_table()
-      thd              thread handle
-      lex              current lex
-      table_ident      table alias if it's used
-      schema_table_idx the type of the INFORMATION_SCHEMA table to be
-                       created
-
-  DESCRIPTION
     This function is used in the parser to convert a SHOW or DESCRIBE
     table_name command to a SELECT from INFORMATION_SCHEMA.
     It prepares a SELECT_LEX and a TABLE_LIST object to represent the
     given command as a SELECT parse tree.
 
-  NOTES
+  @param thd              thread handle
+  @param lex              current lex
+  @param table_ident      table alias if it's used
+  @param schema_table_idx the type of the INFORMATION_SCHEMA table to be
+                          created
+
+  @note
     Due to the way this function works with memory and LEX it cannot
     be used outside the parser (parse tree transformations outside
     the parser break PS and SP).
 
-  RETURN VALUE
+  @retval
     0                 success
+  @retval
     1                 out of memory or SHOW commands are not allowed
     in this version of the server.
 */
@@ -1505,17 +1505,17 @@ int prepare_schema_table(THD *thd, LEX *lex, Table_ident *table_ident,
 }
 
 
-/*
-  Read query from packet and store in thd->query
-  Used in COM_QUERY and COM_STMT_PREPARE
+/**
+  Read query from packet and store in thd->query.
+  Used in COM_QUERY and COM_STMT_PREPARE.
 
-  DESCRIPTION
   Sets the following THD variables:
-      query
-      query_length
+  - query
+  - query_length
 
-  RETURN VALUES
+  @retval
     FALSE ok
+  @retval
     TRUE  error;  In this case thd->fatal_error is set
 */
 
@@ -1655,14 +1655,8 @@ bool sp_process_definer(THD *thd)
 }
 
 
-/*
-  Execute command saved in thd and lex->sql_command
-
-  SYNOPSIS
-    mysql_execute_command()
-      thd                       Thread handle
-
-  IMPLEMENTATION
+/**
+  Execute command saved in thd and lex->sql_command.
 
     Before every operation that can request a write lock for a table
     wait if a global read lock exists. However do not wait if this
@@ -1674,8 +1668,20 @@ bool sp_process_definer(THD *thd)
     global read lock when it succeeds. This needs to be released by
     start_waiting_global_read_lock() after the operation.
 
-  RETURN
+  @param thd                       Thread handle
+
+  @todo
+    - Invalidate the table in the query cache if something changed
+    after unlocking when changes become visible.
+    TODO: this is workaround. right way will be move invalidating in
+    the unlock procedure.
+    - TODO: use check_change_password()
+    - JOIN is not supported yet. TODO
+    - SUSPEND and FOR MIGRATE are not supported yet. TODO
+
+  @retval
     FALSE       OK
+  @retval
     TRUE        Error
 */
 
@@ -4555,20 +4561,19 @@ static bool execute_sqlcom_select(THD *thd, TABLE_LIST *all_tables)
 }
 
 
-/*
+/**
   Check grants for commands which work only with one table.
 
-  SYNOPSIS
-    check_single_table_access()
-    thd			Thread handler
-    privilege		requested privilege
-    all_tables		global table list of query
-    no_errors           FALSE/TRUE - report/don't report error to
+  @param thd			Thread handler
+  @param privilege		requested privilege
+  @param all_tables		global table list of query
+  @param no_errors              FALSE/TRUE - report/don't report error to
                                 the client (using my_error() call).
 
-  RETURN
-    0 - OK
-    1 - access denied, error is sent to client
+  @retval
+    0   OK
+  @retval
+    1   access denied, error is sent to client
 */
 
 bool check_single_table_access(THD *thd, ulong privilege, 
@@ -4606,19 +4611,18 @@ bool check_single_table_access(THD *thd, ulong privilege,
   return 1;
 }
 
-/*
+/**
   Check grants for commands which work only with one table and all other
   tables belonging to subselects or implicitly opened tables.
 
-  SYNOPSIS
-    check_one_table_access()
-    thd			Thread handler
-    privilege		requested privilege
-    all_tables		global table list of query
+  @param thd			Thread handler
+  @param privilege		requested privilege
+  @param all_tables		global table list of query
 
-  RETURN
-    0 - OK
-    1 - access denied, error is sent to client
+  @retval
+    0   OK
+  @retval
+    1   access denied, error is sent to client
 */
 
 bool check_one_table_access(THD *thd, ulong privilege, TABLE_LIST *all_tables)
@@ -4648,25 +4652,26 @@ bool check_one_table_access(THD *thd, ulong privilege, TABLE_LIST *all_tables)
 }
 
 
-/****************************************************************************
-  Get the user (global) and database privileges for all used tables
+/**
+  Get the user (global) and database privileges for all used tables.
+
+  @param save_priv    In this we store global and db level grants for the
+                      table. Note that we don't store db level grants if the
+                      global grants is enough to satisfy the request and the
+                      global grants contains a SELECT grant.
 
-  NOTES
+  @note
     The idea of EXTRA_ACL is that one will be granted access to the table if
     one has the asked privilege on any column combination of the table; For
     example to be able to check a table one needs to have SELECT privilege on
     any column of the table.
 
-  RETURN
+  @retval
     0  ok
-    1  If we can't get the privileges and we don't use table/column grants.
-
-    save_priv	In this we store global and db level grants for the table
-		Note that we don't store db level grants if the global grants
-                is enough to satisfy the request and the global grants contains
-                a SELECT grant.
-****************************************************************************/
-
+  @retval
+    1  If we can't get the privileges and we don't use table/column
+    grants.
+*/
 bool
 check_access(THD *thd, ulong want_access, const char *db, ulong *save_priv,
 	     bool dont_check_global_grants, bool no_errors, bool schema_db)
@@ -4788,22 +4793,21 @@ check_access(THD *thd, ulong want_access, const char *db, ulong *save_priv,
 }
 
 
-/*
-  check for global access and give descriptive error message if it fails
+/**
+  check for global access and give descriptive error message if it fails.
 
-  SYNOPSIS
-    check_global_access()
-    thd			Thread handler
-    want_access		Use should have any of these global rights
+  @param thd			Thread handler
+  @param want_access		Use should have any of these global rights
 
-  WARNING
-    One gets access right if one has ANY of the rights in want_access
+  @warning
+    One gets access right if one has ANY of the rights in want_access.
     This is useful as one in most cases only need one global right,
     but in some case we want to check if the user has SUPER or
     REPL_CLIENT_ACL rights.
 
-  RETURN
+  @retval
     0	ok
+  @retval
     1	Access denied.  In this case an error is sent to the client
 */
 
@@ -4881,27 +4885,26 @@ static bool check_show_access(THD *thd, TABLE_LIST *table)
 }
 
 
-/*
+/**
   Check the privilege for all used tables.
 
-  SYNOPSYS
-    check_table_access()
-      thd          Thread context
-      want_access  Privileges requested
-      tables       List of tables to be checked
-      no_errors    FALSE/TRUE - report/don't report error to
+  @param thd          Thread context
+  @param want_access  Privileges requested
+  @param tables       List of tables to be checked
+  @param no_errors    FALSE/TRUE - report/don't report error to
                       the client (using my_error() call).
 
-  NOTES
+  @note
     Table privileges are cached in the table list for GRANT checking.
     This functions assumes that table list used and
     thd->lex->query_tables_own_last value correspond to each other
     (the latter should be either 0 or point to next_global member
     of one of elements of this table list).
 
-  RETURN VALUE
-    FALSE - OK
-    TRUE  - Access denied
+  @retval
+    FALSE   OK
+  @retval
+    TRUE    Access denied
 */
 
 bool
@@ -5005,17 +5008,16 @@ check_routine_access(THD *thd, ulong want_access,char *db, char *name,
 }
 
 
-/*
-  Check if the routine has any of the routine privileges
+/**
+  Check if the routine has any of the routine privileges.
 
-  SYNOPSIS
-    check_some_routine_access()
-    thd		 Thread handler
-    db           Database name
-    name         Routine name
+  @param thd	       Thread handler
+  @param db           Database name
+  @param name         Routine name
 
-  RETURN
+  @retval
     0            ok
+  @retval
     1            error
 */
 
@@ -5039,17 +5041,15 @@ bool check_some_routine_access(THD *thd, const char *db, const char *name,
 /*
   Check if the given table has any of the asked privileges
 
-  SYNOPSIS
-    check_some_access()
-    thd		 Thread handler
-    want_access	 Bitmap of possible privileges to check for
+  @param thd		 Thread handler
+  @param want_access	 Bitmap of possible privileges to check for
 
-  RETURN
+  @retval
     0  ok
+  @retval
     1  error
 */
 
-
 bool check_some_access(THD *thd, ulong want_access, TABLE_LIST *table)
 {
   ulong access;
@@ -5108,12 +5108,13 @@ bool check_merge_table_access(THD *thd, char *db,
 long max_stack_used;
 #endif
 
-/*
+/**
+  @note
   Note: The 'buf' parameter is necessary, even if it is unused here.
   - fix_fields functions has a "dummy" buffer large enough for the
     corresponding exec. (Thus we only have to check in fix_fields.)
   - Passing to check_stack_overrun() prevents the compiler from removing it.
- */
+*/
 bool check_stack_overrun(THD *thd, long margin,
 			 uchar *buf __attribute__((unused)))
 {
@@ -5167,17 +5168,17 @@ bool my_yyoverflow(short **yyss, YYSTYPE **yyvs, ulong *yystacksize)
 }
 
 
-/*
+/**
   Reset THD part responsible for command processing state.
 
- DESCRIPTION
   This needs to be called before execution of every statement
   (prepared or conventional).
   It is not called by substatements of routines.
 
- TODO
+  @todo
    Make it a method of THD and align its name with the rest of
    reset/end/start/init methods.
+  @todo
    Call it after we use THD for queries, not before.
 */
 
@@ -5322,17 +5323,14 @@ mysql_new_select(LEX *lex, bool move_down)
   DBUG_RETURN(0);
 }
 
-/*
+/**
   Create a select to return the same output as 'SELECT @@var_name'.
 
-  SYNOPSIS
-    create_select_for_variable()
-    var_name		Variable name
+  Used for SHOW COUNT(*) [ WARNINGS | ERROR].
 
-  DESCRIPTION
-    Used for SHOW COUNT(*) [ WARNINGS | ERROR]
+  This will crash with a core dump if the variable doesn't exists.
 
-    This will crash with a core dump if the variable doesn't exists
+  @param var_name		Variable name
 */
 
 void create_select_for_variable(const char *var_name)
@@ -5498,8 +5496,9 @@ void mysql_parse(THD *thd, const char *inBuf, uint length,
   Usable by the replication SQL thread only: just parse a query to know if it
   can be ignored because of replicate-*-table rules.
 
-  RETURN VALUES
+  @retval
     0	cannot be ignored
+  @retval
     1	can be ignored
 */
 
@@ -5524,10 +5523,12 @@ bool mysql_test_parse_for_slave(THD *thd, char *inBuf, uint length)
 
 
 
-/*****************************************************************************
-** Store field definition for create
-** Return 0 if ok
-******************************************************************************/
+/**
+  Store field definition for create.
+
+  @return
+    Return 0 if ok
+*/
 
 bool add_field_to_list(THD *thd, LEX_STRING *field_name, enum_field_types type,
 		       char *length, char *decimals,
@@ -5631,7 +5632,7 @@ bool add_field_to_list(THD *thd, LEX_STRING *field_name, enum_field_types type,
 }
 
 
-/* Store position for column in ALTER TABLE .. ADD column */
+/** Store position for column in ALTER TABLE .. ADD column. */
 
 void store_position_for_column(const char *name)
 {
@@ -5655,10 +5656,9 @@ add_proc_to_list(THD* thd, Item *item)
 }
 
 
-/****************************************************************************
-** save order by and tables in own lists
-****************************************************************************/
-
+/**
+  save order by and tables in own lists.
+*/
 
 bool add_to_list(THD *thd, SQL_LIST &list,Item *item,bool asc)
 {
@@ -5677,24 +5677,23 @@ bool add_to_list(THD *thd, SQL_LIST &list,Item *item,bool asc)
 }
 
 
-/*
-  Add a table to list of used tables
-
-  SYNOPSIS
-    add_table_to_list()
-    table		Table to add
-    alias		alias for table (or null if no alias)
-    table_options	A set of the following bits:
-			TL_OPTION_UPDATING	Table will be updated
-			TL_OPTION_FORCE_INDEX	Force usage of index
-			TL_OPTION_ALIAS	        an alias in multi table DELETE
-    lock_type		How table should be locked
-    use_index		List of indexed used in USE INDEX
-    ignore_index	List of indexed used in IGNORE INDEX
-
-    RETURN
+/**
+  Add a table to list of used tables.
+
+  @param table		Table to add
+  @param alias		alias for table (or null if no alias)
+  @param table_options	A set of the following bits:
+                         - TL_OPTION_UPDATING : Table will be updated
+                         - TL_OPTION_FORCE_INDEX : Force usage of index
+                         - TL_OPTION_ALIAS : an alias in multi table DELETE
+  @param lock_type	How table should be locked
+  @param use_index	List of indexed used in USE INDEX
+  @param ignore_index	List of indexed used in IGNORE INDEX
+
+  @retval
     0	Error
-      #		Pointer to TABLE_LIST element added to the total table list
+  @retval
+    \#	Pointer to TABLE_LIST element added to the total table list
 */
 
 TABLE_LIST *st_select_lex::add_table_to_list(THD *thd,
@@ -5832,14 +5831,9 @@ TABLE_LIST *st_select_lex::add_table_to_list(THD *thd,
 }
 
 
-/*
-  Initialize a new table list for a nested join
-
-  SYNOPSIS
-    init_nested_join()
-    thd         current thread
+/**
+  Initialize a new table list for a nested join.
 
-  DESCRIPTION
     The function initializes a structure of the TABLE_LIST type
     for a nested join. It sets up its nested join list as empty.
     The created structure is added to the front of the current
@@ -5848,9 +5842,12 @@ TABLE_LIST *st_select_lex::add_table_to_list(THD *thd,
     created empty list after having saved the info on the old level
     in the initialized structure.
 
-  RETURN VALUE
-    0,  if success
-    1,  otherwise
+  @param thd         current thread
+
+  @retval
+    0   if success
+  @retval
+    1   otherwise
 */
 
 bool st_select_lex::init_nested_join(THD *thd)
@@ -5876,21 +5873,18 @@ bool st_select_lex::init_nested_join(THD *thd)
 }
 
 
-/*
-  End a nested join table list
-
-  SYNOPSIS
-    end_nested_join()
-    thd         current thread
+/**
+  End a nested join table list.
 
-  DESCRIPTION
     The function returns to the previous join nest level.
     If the current level contains only one member, the function
     moves it one level up, eliminating the nest.
 
-  RETURN VALUE
-    Pointer to TABLE_LIST element added to the total table list, if success
-    0, otherwise
+  @param thd         current thread
+
+  @return
+    - Pointer to TABLE_LIST element added to the total table list, if success
+    - 0, otherwise
 */
 
 TABLE_LIST *st_select_lex::end_nested_join(THD *thd)
@@ -5922,20 +5916,17 @@ TABLE_LIST *st_select_lex::end_nested_join(THD *thd)
 }
 
 
-/*
-  Nest last join operation
-
-  SYNOPSIS
-    nest_last_join()
-    thd         current thread
+/**
+  Nest last join operation.
 
-  DESCRIPTION
   The function nest last join operation as if it was enclosed in braces.
 
-  RETURN VALUE
-    0  Error
-    #  Pointer to TABLE_LIST element created for the new nested join
+  @param thd         current thread
 
+  @retval
+    0  Error
+  @retval
+    \#  Pointer to TABLE_LIST element created for the new nested join
 */
 
 TABLE_LIST *st_select_lex::nest_last_join(THD *thd)
@@ -5980,20 +5971,17 @@ TABLE_LIST *st_select_lex::nest_last_join(THD *thd)
 }
 
 
-/*
-  Add a table to the current join list
-
-  SYNOPSIS
-    add_joined_table()
-    table       the table to add
+/**
+  Add a table to the current join list.
 
-  DESCRIPTION
     The function puts a table in front of the current join list
     of st_select_lex object.
     Thus, joined tables are put into this list in the reverse order
     (the most outer join operation follows first).
 
-  RETURN VALUE
+  @param table       the table to add
+
+  @return
     None
 */
 
@@ -6007,14 +5995,9 @@ void st_select_lex::add_joined_table(TABLE_LIST *table)
 }
 
 
-/*
-  Convert a right join into equivalent left join
-
-  SYNOPSIS
-    convert_right_join()
-    thd         current thread
+/**
+  Convert a right join into equivalent left join.
 
-  DESCRIPTION
     The function takes the current join list t[0],t[1] ... and
     effectively converts it into the list t[1],t[0] ...
     Although the outer_join flag for the new nested table contains
@@ -6022,6 +6005,7 @@ void st_select_lex::add_joined_table(TABLE_LIST *table)
     operation.
 
   EXAMPLES
+  @verbatim
      SELECT * FROM t1 RIGHT JOIN t2 ON on_expr =>
        SELECT * FROM t2 LEFT JOIN t1 ON on_expr
 
@@ -6033,10 +6017,13 @@ void st_select_lex::add_joined_table(TABLE_LIST *table)
 
      SELECT * FROM t1 LEFT JOIN t2 ON on_expr1 RIGHT JOIN t3  ON on_expr2 =>
        SELECT * FROM t3 LEFT JOIN (t1 LEFT JOIN t2 ON on_expr2) ON on_expr1
+   @endverbatim
 
-  RETURN
-    Pointer to the table representing the inner table, if success
-    0, otherwise
+  @param thd         current thread
+
+  @return
+    - Pointer to the table representing the inner table, if success
+    - 0, otherwise
 */
 
 TABLE_LIST *st_select_lex::convert_right_join()
@@ -6052,14 +6039,12 @@ TABLE_LIST *st_select_lex::convert_right_join()
   DBUG_RETURN(tab1);
 }
 
-/*
-  Set lock for all tables in current select level
+/**
+  Set lock for all tables in current select level.
 
-  SYNOPSIS:
-    set_lock_for_tables()
-    lock_type			Lock to set for tables
+  @param lock_type			Lock to set for tables
 
-  NOTE:
+  @note
     If lock is a write lock, then tables->updating is set 1
     This is to get tables_ok to know that the table is updated by the
     query
@@ -6083,27 +6068,29 @@ void st_select_lex::set_lock_for_tables(thr_lock_type lock_type)
 }
 
 
-/*
-  Create a fake SELECT_LEX for a unit
-
-  SYNOPSIS:
-    add_fake_select_lex()
-    thd			   thread handle
+/**
+  Create a fake SELECT_LEX for a unit.
 
-  DESCRIPTION
     The method create a fake SELECT_LEX object for a unit.
     This object is created for any union construct containing a union
     operation and also for any single select union construct of the form
+    @verbatim
     (SELECT ... ORDER BY order_list [LIMIT n]) ORDER BY ... 
+    @endvarbatim
     or of the form
+    @varbatim
     (SELECT ... ORDER BY LIMIT n) ORDER BY ...
+    @endvarbatim
 
-  NOTES
+  @param thd_arg		   thread handle
+
+  @note
     The object is used to retrieve rows from the temporary table
     where the result on the union is obtained.
 
-  RETURN VALUES
+  @retval
     1     on failure to create the object
+  @retval
     0     on success
 */
 
@@ -6145,24 +6132,22 @@ bool st_select_lex_unit::add_fake_select_lex(THD *thd_arg)
 }
 
 
-/*
+/**
   Push a new name resolution context for a JOIN ... ON clause to the
   context stack of a query block.
 
-  SYNOPSIS
-    push_new_name_resolution_context()
-    thd       pointer to current thread
-    left_op   left  operand of the JOIN
-    right_op  rigth operand of the JOIN
-
-  DESCRIPTION
     Create a new name resolution context for a JOIN ... ON clause,
     set the first and last leaves of the list of table references
     to be used for name resolution, and push the newly created
     context to the stack of contexts of the query.
 
-  RETURN
+  @param thd       pointer to current thread
+  @param left_op   left  operand of the JOIN
+  @param right_op  rigth operand of the JOIN
+
+  @retval
     FALSE  if all is OK
+  @retval
     TRUE   if a memory allocation error occured
 */
 
@@ -6182,19 +6167,17 @@ push_new_name_resolution_context(THD *thd,
 }
 
 
-/*
+/**
   Add an ON condition to the second operand of a JOIN ... ON.
 
-  SYNOPSIS
-    add_join_on
-    b     the second operand of a JOIN ... ON
-    expr  the condition to be added to the ON clause
-
-  DESCRIPTION
   Add an ON condition to the right operand of a JOIN ... ON clause.
 
-  RETURN
+  @param b     the second operand of a JOIN ... ON
+  @param expr  the condition to be added to the ON clause
+
+  @retval
     FALSE  if there was some error
+  @retval
     TRUE   if all is OK
 */
 
@@ -6218,18 +6201,10 @@ void add_join_on(TABLE_LIST *b, Item *expr)
 }
 
 
-/*
+/**
   Mark that there is a NATURAL JOIN or JOIN ... USING between two
   tables.
 
-  SYNOPSIS
-    add_join_natural()
-    a			Left join argument
-    b			Right join argument
-    using_fields        Field names from USING clause
-    lex                 The current st_select_lex
-  
-  IMPLEMENTATION
     This function marks that table b should be joined with a either via
     a NATURAL JOIN or via JOIN ... USING. Both join types are special
     cases of each other, so we treat them together. The function
@@ -6240,6 +6215,7 @@ void add_join_on(TABLE_LIST *b, Item *expr)
     was an outer join.
 
   EXAMPLE
+  @verbatim
      SELECT * FROM t1 NATURAL LEFT JOIN t2
       <=>
      SELECT * FROM t1 LEFT JOIN t2 ON (t1.i=t2.i and t1.j=t2.j ... )
@@ -6251,9 +6227,11 @@ void add_join_on(TABLE_LIST *b, Item *expr)
      SELECT * FROM t1 JOIN t2 USING(j) WHERE <some_cond>
       <=>
      SELECT * FROM t1, t2 WHERE (t1.j=t2.j and <some_cond>)
+   @endverbatim
 
-  RETURN
-    None
+  @param a		  Left join argument
+  @param b		  Right join argument
+  @param using_fields    Field names from USING clause
 */
 
 void add_join_natural(TABLE_LIST *a, TABLE_LIST *b, List<String> *using_fields,
@@ -6264,23 +6242,23 @@ void add_join_natural(TABLE_LIST *a, TABLE_LIST *b, List<String> *using_fields,
 }
 
 
-/*
+/**
   Reload/resets privileges and the different caches.
 
-  SYNOPSIS
-    reload_acl_and_cache()
-    thd			Thread handler (can be NULL!)
-    options             What should be reset/reloaded (tables, privileges,
+  @param thd		    Thread handler (can be NULL!)
+  @param options           What should be reset/reloaded (tables, privileges,
                            slave...)
-    tables              Tables to flush (if any)
-    write_to_binlog     Depending on 'options', it may be very bad to write the
-                        query to the binlog (e.g. FLUSH SLAVE); this is a
-                        pointer where reload_acl_and_cache() will put 0 if
-                        it thinks we really should not write to the binlog.
+  @param tables            Tables to flush (if any)
+  @param write_to_binlog   Depending on 'options', it may be very bad to
+                           write the query to the binlog (e.g. FLUSH SLAVE);
+                           this is a pointer where reload_acl_and_cache()
+                           will put 0 if it thinks we really should not write
+                           to the binlog.
                            Otherwise it will put 1.
 
-  RETURN
+  @retval
     0	 ok
+  @retval
     !=0   error.  thd->killed or thd->net.report_error is set
 */
 
@@ -6454,16 +6432,14 @@ bool reload_acl_and_cache(THD *thd, ulong options, TABLE_LIST *tables,
 }
 
 
-/*
-  kills a thread
+/**
+  kill on thread.
 
-  SYNOPSIS
-    kill_one_thread()
-    thd			Thread class
-    id			Thread id
-    only_kill_query     Should it kill the query or the connection
+  @param thd			Thread class
+  @param id			Thread id
+  @param only_kill_query        Should it kill the query or the connection
 
-  NOTES
+  @note
     This is written such that we have a short lock on LOCK_thread_count
 */
 
@@ -6523,7 +6499,7 @@ void sql_kill(THD *thd, ulong id, bool only_kill_query)
 }
 
 
-	/* If pointer is not a null pointer, append filename to it */
+/** If pointer is not a null pointer, append filename to it. */
 
 bool append_file_to_dir(THD *thd, const char **filename_ptr,
                         const char *table_name)
@@ -6550,14 +6526,12 @@ bool append_file_to_dir(THD *thd, const char **filename_ptr,
 }
 
 
-/*
-  Check if the select is a simple select (not an union)
-
-  SYNOPSIS
-    check_simple_select()
+/**
+  Check if the select is a simple select (not an union).
 
-  RETURN VALUES
+  @retval
     0	ok
+  @retval
     1	error	; In this case the error messege is sent to the client
 */
 
@@ -6614,17 +6588,15 @@ Comp_creator *comp_ne_creator(bool invert)
 }
 
 
-/*
-  Construct ALL/ANY/SOME subquery Item
+/**
+  Construct ALL/ANY/SOME subquery Item.
 
-  SYNOPSIS
-    all_any_subquery_creator()
-    left_expr - pointer to left expression
-    cmp - compare function creator
-    all - true if we create ALL subquery
-    select_lex - pointer on parsed subquery structure
+  @param left_expr   pointer to left expression
+  @param cmp         compare function creator
+  @param all         true if we create ALL subquery
+  @param select_lex  pointer on parsed subquery structure
 
-  RETURN VALUE
+  @return
     constructed Item (or 0 if out of memory)
 */
 Item * all_any_subquery_creator(Item *left_expr,
@@ -6647,16 +6619,15 @@ Item * all_any_subquery_creator(Item *left_expr,
 }
 
 
-/*
-  Multi update query pre-check
+/**
+  Multi update query pre-check.
 
-  SYNOPSIS
-    multi_update_precheck()
-    thd		Thread handler
-    tables	Global/local table list (have to be the same)
+  @param thd		Thread handler
+  @param tables	Global/local table list (have to be the same)
 
-  RETURN VALUE
+  @retval
     FALSE OK
+  @retval
     TRUE  Error
 */
 
@@ -6724,16 +6695,15 @@ bool multi_update_precheck(THD *thd, TABLE_LIST *tables)
   DBUG_RETURN(FALSE);
 }
 
-/*
-  Multi delete query pre-check
+/**
+  Multi delete query pre-check.
 
-  SYNOPSIS
-    multi_delete_precheck()
-    thd			Thread handler
-    tables		Global/local table list
+  @param thd			Thread handler
+  @param tables		Global/local table list
 
-  RETURN VALUE
+  @retval
     FALSE OK
+  @retval
     TRUE  error
 */
 
@@ -6773,17 +6743,16 @@ bool multi_delete_precheck(THD *thd, TABLE_LIST *tables)
 }
 
 
-/*
+/**
   Link tables in auxilary table list of multi-delete with corresponding
   elements in main table list, and set proper locks for them.
 
-  SYNOPSIS
-    multi_delete_set_locks_and_link_aux_tables()
-      lex - pointer to LEX representing multi-delete
+  @param lex   pointer to LEX representing multi-delete
 
-  RETURN VALUE
-    FALSE - success
-    TRUE  - error
+  @retval
+    FALSE   success
+  @retval
+    TRUE    error
 */
 
 bool multi_delete_set_locks_and_link_aux_tables(LEX *lex)
@@ -6826,16 +6795,15 @@ bool multi_delete_set_locks_and_link_aux_tables(LEX *lex)
 }
 
 
-/*
-  simple UPDATE query pre-check
+/**
+  simple UPDATE query pre-check.
 
-  SYNOPSIS
-    update_precheck()
-    thd		Thread handler
-    tables	Global table list
+  @param thd		Thread handler
+  @param tables	Global table list
 
-  RETURN VALUE
+  @retval
     FALSE OK
+  @retval
     TRUE  Error
 */
 
@@ -6851,16 +6819,15 @@ bool update_precheck(THD *thd, TABLE_LIST *tables)
 }
 
 
-/*
-  simple DELETE query pre-check
+/**
+  simple DELETE query pre-check.
 
-  SYNOPSIS
-    delete_precheck()
-    thd		Thread handler
-    tables	Global table list
+  @param thd		Thread handler
+  @param tables	Global table list
 
-  RETURN VALUE
+  @retval
     FALSE  OK
+  @retval
     TRUE   error
 */
 
@@ -6875,16 +6842,15 @@ bool delete_precheck(THD *thd, TABLE_LIST *tables)
 }
 
 
-/*
-  simple INSERT query pre-check
+/**
+  simple INSERT query pre-check.
 
-  SYNOPSIS
-    insert_precheck()
-    thd		Thread handler
-    tables	Global table list
+  @param thd		Thread handler
+  @param tables	Global table list
 
-  RETURN VALUE
+  @retval
     FALSE  OK
+  @retval
     TRUE   error
 */
 
@@ -6932,17 +6898,16 @@ static bool check_show_create_table_access(THD *thd, TABLE_LIST *table)
 }
 
 
-/*
-  CREATE TABLE query pre-check
+/**
+  CREATE TABLE query pre-check.
 
-  SYNOPSIS
-    create_table_precheck()
-    thd			Thread handler
-    tables		Global table list
-    create_table	Table which will be created
+  @param thd			Thread handler
+  @param tables		Global table list
+  @param create_table	        Table which will be created
 
-  RETURN VALUE
+  @retval
     FALSE   OK
+  @retval
     TRUE   Error
 */
 
@@ -7008,15 +6973,13 @@ bool create_table_precheck(THD *thd, TABLE_LIST *tables,
 }
 
 
-/*
-  negate given expression
+/**
+  negate given expression.
 
-  SYNOPSIS
-    negate_expression()
-    thd  thread handler
-    expr expression for negation
+  @param thd  thread handler
+  @param expr expression for negation
 
-  RETURN
+  @return
     negated expression
 */
 
@@ -7043,14 +7006,12 @@ Item *negate_expression(THD *thd, Item *expr)
   return new Item_func_not(expr);
 }
 
-/*
-  Set the specified definer to the default value, which is the current user in
-  the thread.
+/**
+  Set the specified definer to the default value, which is the
+  current user in the thread.
 
-  SYNOPSIS
-    get_default_definer()
-    thd       [in] thread handler
-    definer   [out] definer
+  @param[in]  thd       thread handler
+  @param[out] definer   definer
 */
  
 void get_default_definer(THD *thd, LEX_USER *definer)
@@ -7065,17 +7026,15 @@ void get_default_definer(THD *thd, LEX_USER *definer)
 }
 
 
-/*
+/**
   Create default definer for the specified THD.
 
-  SYNOPSIS
-    create_default_definer()
-    thd         [in] thread handler
+  @param[in] thd         thread handler
 
-  RETURN
-    On success, return a valid pointer to the created and initialized
+  @return
+    - On success, return a valid pointer to the created and initialized
     LEX_USER, which contains definer information.
-    On error, return 0.
+    - On error, return 0.
 */
 
 LEX_USER *create_default_definer(THD *thd)
@@ -7091,19 +7050,17 @@ LEX_USER *create_default_definer(THD *thd)
 }
 
 
-/*
+/**
   Create definer with the given user and host names.
 
-  SYNOPSIS
-    create_definer()
-    thd         [in] thread handler
-    user_name   [in] user name
-    host_name   [in] host name
+  @param[in] thd          thread handler
+  @param[in] user_name    user name
+  @param[in] host_name    host name
 
-  RETURN
-    On success, return a valid pointer to the created and initialized
+  @return
+    - On success, return a valid pointer to the created and initialized
     LEX_USER, which contains definer information.
-    On error, return 0.
+    - On error, return 0.
 */
 
 LEX_USER *create_definer(THD *thd, LEX_STRING *user_name, LEX_STRING *host_name)
@@ -7122,18 +7079,16 @@ LEX_USER *create_definer(THD *thd, LEX_STRING *user_name, LEX_STRING *host_name)
 }
 
 
-/*
+/**
   Retuns information about user or current user.
 
-  SYNOPSIS
-    get_current_user()
-    thd         [in] thread handler
-    user        [in] user
+  @param[in] thd          thread handler
+  @param[in] user         user
 
-  RETURN
-    On success, return a valid pointer to initialized
+  @return
+    - On success, return a valid pointer to initialized
     LEX_USER, which contains user information.
-    On error, return 0.
+    - On error, return 0.
 */
 
 LEX_USER *get_current_user(THD *thd, LEX_USER *user)
@@ -7145,17 +7100,16 @@ LEX_USER *get_current_user(THD *thd, LEX_USER *user)
 }
 
 
-/*
+/**
   Check that byte length of a string does not exceed some limit.
 
-  SYNOPSIS
-  check_string_byte_length()
-      str              string to be checked
-      err_msg          error message to be displayed if the string is too long
-      max_byte_length  max length in bytes
+  @param str         string to be checked
+  @param err_msg     error message to be displayed if the string is too long
+  @param max_length  max length
 
-  RETURN
+  @retval
     FALSE   the passed string is not longer than max_length
+  @retval
     TRUE    the passed string is longer than max_length
 
   NOTE

sql/sql_prepare.cc

@@ -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
+
 This file contains the implementation of prepared statements.
 
 When one prepares a statement:
@@ -28,11 +30,13 @@ When one prepares a statement:
   - Without executing the query, return back to client the total
     number of parameters along with result-set metadata information
     (if any) in the following format:
+    @verbatim
     [STMT_ID:4]
     [Column_count:2]
     [Param_count:2]
     [Params meta info (stubs only for now)]  (if Param_count > 0)
     [Columns meta info] (if Column_count > 0)
+    @endverbatim
 
   During prepare the tables used in a statement are opened, but no
   locks are acquired.  Table opening will block any DDL during the
@@ -45,12 +49,14 @@ When one executes a statement:
   - Server gets the command 'COM_STMT_EXECUTE' to execute the
     previously prepared query. If there are any parameter markers, then the
     client will send the data in the following format:
+    @verbatim
     [COM_STMT_EXECUTE:1]
     [STMT_ID:4]
     [NULL_BITS:(param_count+7)/8)]
     [TYPES_SUPPLIED_BY_CLIENT(0/1):1]
     [[length]data]
     [[length]data] .. [[length]data].
+    @endverbatim
     (Note: Except for string/binary types; all other types will not be
     supplied with length field)
   - If it is a first execute or types of parameters were altered by client,
@@ -75,8 +81,7 @@ When one supplies long data for a placeholder:
     server doesn't care; also, the server doesn't notify the client whether
     it got the data or not; if there is any error, then it will be returned
     at statement execute.
-
-***********************************************************************/
+*/
 
 #include "mysql_priv.h"
 #include "sql_select.h" // for JOIN
@@ -91,7 +96,9 @@ When one supplies long data for a placeholder:
 #include <mysql_com.h>
 #endif
 
-/* A result class used to send cursor rows using the binary protocol. */
+/**
+  A result class used to send cursor rows using the binary protocol.
+*/
 
 class Select_fetch_protocol_binary: public select_send
 {
@@ -112,7 +119,7 @@ class Select_fetch_protocol_binary: public select_send
 /****************************************************************************/
 
 /**
-  @brief Prepared_statement: a statement that can contain placeholders
+  Prepared_statement: a statement that can contain placeholders.
 */
 
 class Prepared_statement: public Statement
@@ -176,20 +183,17 @@ inline bool is_param_null(const uchar *pos, ulong param_no)
   return pos[param_no/8] & (1 << (param_no & 7));
 }
 
-/*
+/**
   Find a prepared statement in the statement map by id.
 
-  SYNOPSIS
-    find_prepared_statement()
-      thd                thread handle
-      id                 statement id
-      where              the place from which this function is called (for
-                         error reporting).
-
-  DESCRIPTION
     Try to find a prepared statement and set THD error if it's not found.
 
-  RETURN VALUE
+  @param thd                thread handle
+  @param id                 statement id
+  @param where              the place from which this function is called (for
+                            error reporting).
+
+  @return
     0 if the statement was not found, a pointer otherwise.
 */
 
@@ -214,13 +218,13 @@ find_prepared_statement(THD *thd, ulong id, const char *where)
 }
 
 
-/*
+/**
   Send prepared statement id and metadata to the client after prepare.
 
-  SYNOPSIS
-    send_prep_stmt()
+  @todo
+    Fix this nasty upcast from List<Item_param> to List<Item>
 
-  RETURN VALUE
+  @return
     0 in case of success, 1 otherwise
 */
 
@@ -265,24 +269,22 @@ static bool send_prep_stmt(Prepared_statement *stmt,
 #endif /*!EMBEDDED_LIBRARY*/
 
 
-/*
+#ifndef EMBEDDED_LIBRARY
+
+/**
   Read the length of the parameter data and return it back to
   the caller.
 
-  SYNOPSIS
-    get_param_length()
-      packet             a pointer to the data
-      len                remaining packet length
-
-  DESCRIPTION
     Read data length, position the packet to the first byte after it,
     and return the length to the caller.
 
-  RETURN VALUE
+  @param packet             a pointer to the data
+  @param len                remaining packet length
+
+  @return
     Length of data piece.
 */
 
-#ifndef EMBEDDED_LIBRARY
 static ulong get_param_length(uchar **packet, ulong len)
 {
   reg1 uchar *pos= *packet;
@@ -323,16 +325,9 @@ static ulong get_param_length(uchar **packet, ulong len)
 #define get_param_length(packet, len) len
 #endif /*!EMBEDDED_LIBRARY*/
 
- /*
+/**
   Data conversion routines.
 
-   SYNOPSIS
-     set_param_xx()
-       param             parameter item
-       pos               input data buffer
-       len               length of data in the buffer
-
-  DESCRIPTION
     All these functions read the data from pos, convert it to requested
     type and assign to param; pos is advanced to predefined length.
 
@@ -340,8 +335,9 @@ static ulong get_param_length(uchar **packet, ulong len)
     (i.e. when input types altered) and for all subsequent executions
     we don't read any values for this.
 
-  RETURN VALUE
-    none
+  @param  param             parameter item
+  @param  pos               input data buffer
+  @param  len               length of data in the buffer
 */
 
 static void set_param_tiny(Item_param *param, uchar **pos, ulong len)
@@ -443,6 +439,10 @@ static void set_param_decimal(Item_param *param, uchar **pos, ulong len)
   libmysql.c (store_param_{time,date,datetime}).
 */
 
+/**
+  @todo
+    Add warning 'Data truncated' here
+*/
 static void set_param_time(Item_param *param, uchar **pos, ulong len)
 {
   MYSQL_TIME tm;
@@ -532,6 +532,10 @@ static void set_param_date(Item_param *param, uchar **pos, ulong len)
 }
 
 #else/*!EMBEDDED_LIBRARY*/
+/**
+  @todo
+    Add warning 'Data truncated' here
+*/
 void set_param_time(Item_param *param, uchar **pos, ulong len)
 {
   MYSQL_TIME tm= *((MYSQL_TIME*)*pos);
@@ -684,14 +688,13 @@ static void setup_one_conversion_function(THD *thd, Item_param *param,
 }
 
 #ifndef EMBEDDED_LIBRARY
-/*
+/**
   Routines to assign parameters from data supplied by the client.
 
-  DESCRIPTION
     Update the parameter markers by reading data from the packet and
     and generate a valid query for logging.
 
-  NOTES
+  @note
     This function, along with other _with_log functions is called when one of
     binary, slow or general logs is open. Logging of prepared statements in
     all cases is performed by means of conventional queries: if parameter
@@ -699,21 +702,28 @@ static void setup_one_conversion_function(THD *thd, Item_param *param,
     replaced with its actual value; if we're logging a [Dynamic] SQL
     prepared statement, parameter markers are replaced with variable names.
     Example:
+    @verbatim
      mysql_stmt_prepare("UPDATE t1 SET a=a*1.25 WHERE a=?")
        --> general logs gets [Prepare] UPDATE t1 SET a*1.25 WHERE a=?"
      mysql_stmt_execute(stmt);
        --> general and binary logs get
                              [Execute] UPDATE t1 SET a*1.25 WHERE a=1"
+    @endverbatim
+
     If a statement has been prepared using SQL syntax:
+    @verbatim
      PREPARE stmt FROM "UPDATE t1 SET a=a*1.25 WHERE a=?"
        --> general log gets
                                  [Query]   PREPARE stmt FROM "UPDATE ..."
      EXECUTE stmt USING @a
        --> general log gets
                              [Query]   EXECUTE stmt USING @a;
+    @endverbatim
 
-  RETURN VALUE
-   0 if success, 1 otherwise
+  @retval
+    0  if success
+  @retval
+    1  otherwise
 */
 
 static bool insert_params_with_log(Prepared_statement *stmt, uchar *null_array,
@@ -829,12 +839,12 @@ static bool setup_conversion_functions(Prepared_statement *stmt,
 
 #else
 
-/*
+/**
   Embedded counterparts of parameter assignment routines.
 
-  DESCRIPTION
     The main difference between the embedded library and the server is
     that in embedded case we don't serialize/deserialize parameters data.
+
     Additionally, for unknown reason, the client-side flag raised for
     changed types of placeholders is ignored and we simply setup conversion
     functions at each execute (TODO: fix).
@@ -928,15 +938,14 @@ static bool emb_insert_params_with_log(Prepared_statement *stmt,
 #endif /*!EMBEDDED_LIBRARY*/
 
 
-/*
+/**
   Assign prepared statement parameters from user variables.
 
-  SYNOPSIS
-    insert_params_from_vars()
-      stmt      Statement
-      varnames  List of variables. Caller must ensure that number of variables
-                in the list is equal to number of statement parameters
-      query     Ignored
+  @param stmt      Statement
+  @param varnames  List of variables. Caller must ensure that number
+                   of variables in the list is equal to number of statement
+                   parameters
+  @param query     Ignored
 */
 
 static bool insert_params_from_vars(Prepared_statement *stmt,
@@ -965,16 +974,15 @@ static bool insert_params_from_vars(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Do the same as insert_params_from_vars but also construct query text for
   binary log.
 
-  SYNOPSIS
-    insert_params_from_vars()
-      stmt      Prepared statement
-      varnames  List of variables. Caller must ensure that number of variables
-                in the list is equal to number of statement parameters
-      query     The query with parameter markers replaced with corresponding
+  @param stmt      Prepared statement
+  @param varnames  List of variables. Caller must ensure that number of
+                   variables in the list is equal to number of statement
+                   parameters
+  @param query     The query with parameter markers replaced with corresponding
                    user variables that were used to execute the query.
 */
 
@@ -1024,16 +1032,15 @@ static bool insert_params_from_vars_with_log(Prepared_statement *stmt,
   DBUG_RETURN(0);
 }
 
-/*
+/**
   Validate INSERT statement.
 
-  SYNOPSIS
-    mysql_test_insert()
-      stmt               prepared statement
-      tables             global/local table list
+  @param stmt               prepared statement
+  @param tables             global/local table list
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1112,17 +1119,20 @@ static bool mysql_test_insert(Prepared_statement *stmt,
 }
 
 
-/*
-  Validate UPDATE statement
+/**
+  Validate UPDATE statement.
+
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
 
-  SYNOPSIS
-    mysql_test_update()
-      stmt               prepared statement
-      tables             list of tables used in this query
+  @todo
+    - here we should send types of placeholders to the client.
 
-  RETURN VALUE
+  @retval
     0                 success
+  @retval
     1                 error, error message is set in THD
+  @retval
     2                 convert to multi_update
 */
 
@@ -1196,16 +1206,15 @@ static int mysql_test_update(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Validate DELETE statement.
 
-  SYNOPSIS
-    mysql_test_delete()
-      stmt               prepared statement
-      tables             list of tables used in this query
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1233,21 +1242,20 @@ static bool mysql_test_delete(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Validate SELECT statement.
 
-  SYNOPSIS
-    mysql_test_select()
-      stmt               prepared statement
-      tables             list of tables used in the query
-
-  DESCRIPTION
     In case of success, if this query is not EXPLAIN, send column list info
     back to the client.
 
-  RETURN VALUE
+  @param stmt               prepared statement
+  @param tables             list of tables used in the query
+
+  @retval
     0                 success
+  @retval
     1                 error, error message is set in THD
+  @retval
     2                 success, and statement metadata has been sent
 */
 
@@ -1313,17 +1321,16 @@ static int mysql_test_select(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Validate and prepare for execution DO statement expressions.
 
-  SYNOPSIS
-    mysql_test_do_fields()
-      stmt               prepared statement
-      tables             list of tables used in this query
-      values             list of expressions
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
+  @param values             list of expressions
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1343,17 +1350,16 @@ static bool mysql_test_do_fields(Prepared_statement *stmt,
 }
 
 
-/*
-  Validate and prepare for execution SET statement expressions
+/**
+  Validate and prepare for execution SET statement expressions.
 
-  SYNOPSIS
-    mysql_test_set_fields()
-      stmt               prepared statement
-      tables             list of tables used in this query
-      values             list of expressions
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
+  @param values             list of expressions
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1381,23 +1387,22 @@ static bool mysql_test_set_fields(Prepared_statement *stmt,
 }
 
 
-/*
-  Check internal SELECT of the prepared command
+/**
+  Check internal SELECT of the prepared command.
 
-  SYNOPSIS
-    select_like_stmt_test()
-      stmt                      prepared statement
-      specific_prepare          function of command specific prepare
-      setup_tables_done_option  options to be passed to LEX::unit.prepare()
+  @param stmt                      prepared statement
+  @param specific_prepare          function of command specific prepare
+  @param setup_tables_done_option  options to be passed to LEX::unit.prepare()
 
-  NOTE
+  @note
     This function won't directly open tables used in select. They should
     be opened either by calling function (and in this case you probably
     should use select_like_stmt_test_with_open()) or by
     "specific_prepare" call (like this happens in case of multi-update).
 
-  RETURN VALUE
+  @retval
     FALSE                success
+  @retval
     TRUE                 error, error message is set in THD
 */
 
@@ -1420,20 +1425,19 @@ static bool select_like_stmt_test(Prepared_statement *stmt,
   DBUG_RETURN(lex->unit.prepare(thd, 0, setup_tables_done_option));
 }
 
-/*
+/**
   Check internal SELECT of the prepared command (with opening of used
   tables).
 
-  SYNOPSIS
-    select_like_stmt_test_with_open()
-      stmt                      prepared statement
-      tables                    list of tables to be opened before calling
-                                specific_prepare function
-      specific_prepare          function of command specific prepare
-      setup_tables_done_option  options to be passed to LEX::unit.prepare()
+  @param stmt                      prepared statement
+  @param tables                    list of tables to be opened
+                                   before calling specific_prepare function
+  @param specific_prepare          function of command specific prepare
+  @param setup_tables_done_option  options to be passed to LEX::unit.prepare()
 
-  RETURN VALUE
+  @retval
     FALSE                success
+  @retval
     TRUE                 error
 */
 
@@ -1459,16 +1463,15 @@ select_like_stmt_test_with_open(Prepared_statement *stmt,
 }
 
 
-/*
-  Validate and prepare for execution CREATE TABLE statement
+/**
+  Validate and prepare for execution CREATE TABLE statement.
 
-  SYNOPSIS
-    mysql_test_create_table()
-      stmt               prepared statement
-      tables             list of tables used in this query
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1512,17 +1515,16 @@ static bool mysql_test_create_table(Prepared_statement *stmt)
 }
 
 
-/*
+/**
   Validate and prepare for execution a multi update statement.
 
-  SYNOPSIS
-    mysql_test_multiupdate()
-      stmt               prepared statement
-      tables             list of tables used in this query
-      converted          converted to multi-update from usual update
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
+  @param converted          converted to multi-update from usual update
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1539,16 +1541,15 @@ static bool mysql_test_multiupdate(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Validate and prepare for execution a multi delete statement.
 
-  SYNOPSIS
-    mysql_test_multidelete()
-      stmt               prepared statement
-      tables             list of tables used in this query
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message in THD is set.
 */
 
@@ -1579,15 +1580,13 @@ static bool mysql_test_multidelete(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Wrapper for mysql_insert_select_prepare, to make change of local tables
   after open_normal_and_derived_tables() call.
 
-  SYNOPSIS
-    mysql_insert_select_prepare_tester()
-      thd                thread handle
+  @param thd                thread handle
 
-  NOTE
+  @note
     We need to remove the first local table after
     open_normal_and_derived_tables(), because mysql_handle_derived
     uses local tables lists.
@@ -1608,16 +1607,15 @@ static bool mysql_insert_select_prepare_tester(THD *thd)
 }
 
 
-/*
+/**
   Validate and prepare for execution INSERT ... SELECT statement.
 
-  SYNOPSIS
-    mysql_test_insert_select()
-      stmt               prepared statement
-      tables             list of tables used in this query
+  @param stmt               prepared statement
+  @param tables             list of tables used in this query
 
-  RETURN VALUE
+  @retval
     FALSE             success
+  @retval
     TRUE              error, error message is set in THD
 */
 
@@ -1651,22 +1649,20 @@ static bool mysql_test_insert_select(Prepared_statement *stmt,
 }
 
 
-/*
+/**
   Perform semantic analysis of the parsed tree and send a response packet
   to the client.
 
-  SYNOPSIS
-    check_prepared_statement()
-      stmt               prepared statement
-
-  DESCRIPTION
     This function
     - opens all tables and checks access rights
     - validates semantics of statement columns and SQL functions
       by calling fix_fields.
 
-  RETURN VALUE
+  @param stmt               prepared statement
+
+  @retval
     FALSE             success, statement metadata is sent to client
+  @retval
     TRUE              error, error message is set in THD (but not sent)
 */
 
@@ -1834,7 +1830,7 @@ static bool check_prepared_statement(Prepared_statement *stmt,
   DBUG_RETURN(TRUE);
 }
 
-/*
+/**
   Initialize array of parameters in statement from LEX.
   (We need to have quick access to items by number in mysql_stmt_get_longdata).
   This is to avoid using malloc/realloc in the parser.
@@ -1870,31 +1866,28 @@ static bool init_param_array(Prepared_statement *stmt)
 }
 
 
-/*
+/**
   COM_STMT_PREPARE handler.
 
-  SYNOPSIS
-    mysql_stmt_prepare()
-      packet             query to be prepared
-      packet_length      query string length, including ignored
-                         trailing NULL or quote char.
-
-  DESCRIPTION
     Given a query string with parameter markers, create a prepared
     statement from it and send PS info back to the client.
 
-  NOTES
-    This function parses the query and sends the total number of parameters
-    and resultset metadata information back to client (if any), without
-    executing the query i.e. without any log/disk writes. This allows the
-    queries to be re-executed without re-parsing during execute.
-
     If parameter markers are found in the query, then store the information
     using Item_param along with maintaining a list in lex->param_array, so
     that a fast and direct retrieval can be made without going through all
     field items.
 
-  RETURN VALUE
+  @param packet             query to be prepared
+  @param packet_length      query string length, including ignored
+                            trailing NULL or quote char.
+
+  @note
+    This function parses the query and sends the total number of parameters
+    and resultset metadata information back to client (if any), without
+    executing the query i.e. without any log/disk writes. This allows the
+    queries to be re-executed without re-parsing during execute.
+
+  @return
     none: in case of success a new statement id and metadata is sent
     to the client, otherwise an error message is set in THD.
 */
@@ -1944,22 +1937,22 @@ void mysql_stmt_prepare(THD *thd, const char *packet, uint packet_length)
   DBUG_VOID_RETURN;
 }
 
-/*
-  SYNOPSIS
-    get_dynamic_sql_string()
-      lex       in      main lex
-      query_len out     length of the SQL statement (is set only
-                        in case of success)
+/**
+  Get an SQL statement text from a user variable or from plain text.
 
-  DESCRIPTION
-    Get an SQL statement text from a user variable or from plain
-    text. If the statement is plain text, just assign the
+  If the statement is plain text, just assign the
   pointers, otherwise allocate memory in thd->mem_root and copy
   the contents of the variable, possibly with character
   set conversion.
 
-  RETURN VALUE
-    non-zero success, 0 in case of error (out of memory)
+  @param[in]  lex               main lex
+  @param[out] query_len         length of the SQL statement (is set only
+    in case of success)
+
+  @retval
+    non-zero  success
+  @retval
+    0         in case of error (out of memory)
 */
 
 static const char *get_dynamic_sql_string(LEX *lex, uint *query_len)
@@ -2037,7 +2030,7 @@ static const char *get_dynamic_sql_string(LEX *lex, uint *query_len)
 }
 
 
-/* Init PS/SP specific parse tree members.  */
+/** Init PS/SP specific parse tree members.  */
 
 static void init_stmt_after_parse(LEX *lex)
 {
@@ -2050,19 +2043,16 @@ static void init_stmt_after_parse(LEX *lex)
    sl->uncacheable&= ~UNCACHEABLE_PREPARE;
 }
 
-/*
+/**
   SQLCOM_PREPARE implementation.
 
-  SYNOPSIS
-    mysql_sql_stmt_prepare()
-      thd     thread handle
-
-  DESCRIPTION
     Prepare an SQL prepared statement. This is called from
     mysql_execute_command and should therefore behave like an
     ordinary query (e.g. should not reset any global THD data).
 
-  RETURN VALUE
+  @param thd     thread handle
+
+  @return
     none: in case of success, OK packet is sent to the client,
     otherwise an error message is set in THD
 */
@@ -2118,7 +2108,14 @@ void mysql_sql_stmt_prepare(THD *thd)
   DBUG_VOID_RETURN;
 }
 
-/* Reinit prepared statement/stored procedure before execution */
+/**
+  Reinit prepared statement/stored procedure before execution.
+
+  @todo
+    When the new table structure is ready, then have a status bit
+    to indicate the table is altered, and re-do the setup_*
+    and open the tables back.
+*/
 
 void reinit_stmt_before_use(THD *thd, LEX *lex)
 {
@@ -2224,12 +2221,10 @@ void reinit_stmt_before_use(THD *thd, LEX *lex)
 }
 
 
-/*
-  Clears parameters from data left from previous execution or long data
+/**
+  Clears parameters from data left from previous execution or long data.
 
-  SYNOPSIS
-    reset_stmt_params()
-      stmt               prepared statement for which parameters should
+  @param stmt               prepared statement for which parameters should
                             be reset
 */
 
@@ -2242,22 +2237,19 @@ static void reset_stmt_params(Prepared_statement *stmt)
 }
 
 
-/*
+/**
   COM_STMT_EXECUTE handler: execute a previously prepared statement.
 
-  SYNOPSIS
-    mysql_stmt_execute()
-      thd                current thread
-      packet             parameter types and data, if any
-      packet_length      packet length, including the terminator character.
-
-  DESCRIPTION
     If there are any parameters, then replace parameter markers with the
     data supplied from the client, and then execute the statement.
     This function uses binary protocol to send a possible result set
     to the client.
 
-  RETURN VALUE
+  @param thd                current thread
+  @param packet_arg         parameter types and data, if any
+  @param packet_length      packet length, including the terminator character.
+
+  @return
     none: in case of success OK packet or a result set is sent to the
     client, otherwise an error message is set in THD.
 */
@@ -2331,14 +2323,9 @@ void mysql_stmt_execute(THD *thd, char *packet_arg, uint packet_length)
 }
 
 
-/*
+/**
   SQLCOM_EXECUTE implementation.
 
-  SYNOPSIS
-    mysql_sql_stmt_execute()
-      thd                thread handle
-
-  DESCRIPTION
     Execute prepared statement using parameter values from
     lex->prepared_stmt_params and send result to the client using
     text protocol. This is called from mysql_execute_command and
@@ -2346,7 +2333,9 @@ void mysql_stmt_execute(THD *thd, char *packet_arg, uint packet_length)
     global THD data, such as warning count, server status, etc).
     This function uses text protocol to send a possible result set.
 
-  RETURN
+  @param thd                thread handle
+
+  @return
     none: in case of success, OK (or result set) packet is sent to the
     client, otherwise an error is set in THD
 */
@@ -2398,14 +2387,12 @@ void mysql_sql_stmt_execute(THD *thd)
 }
 
 
-/*
-  COM_STMT_FETCH handler: fetches requested amount of rows from cursor
+/**
+  COM_STMT_FETCH handler: fetches requested amount of rows from cursor.
 
-  SYNOPSIS
-    mysql_stmt_fetch()
-      thd                Thread handle
-      packet             Packet from client (with stmt_id & num_rows)
-      packet_length      Length of packet
+  @param thd                Thread handle
+  @param packet             Packet from client (with stmt_id & num_rows)
+  @param packet_length      Length of packet
 */
 
 void mysql_stmt_fetch(THD *thd, char *packet, uint packet_length)
@@ -2456,14 +2443,9 @@ void mysql_stmt_fetch(THD *thd, char *packet, uint packet_length)
 }
 
 
-/*
+/**
   Reset a prepared statement in case there was a recoverable error.
-  SYNOPSIS
-    mysql_stmt_reset()
-      thd                Thread handle
-      packet             Packet with stmt id
 
-  DESCRIPTION
     This function resets statement to the state it was right after prepare.
     It can be used to:
     - clear an error happened during mysql_stmt_send_long_data
@@ -2472,6 +2454,9 @@ void mysql_stmt_fetch(THD *thd, char *packet, uint packet_length)
     - close an open cursor
     Sends 'OK' packet in case of success (statement was reset)
     or 'ERROR' packet (unrecoverable error/statement not found/etc).
+
+  @param thd                Thread handle
+  @param packet             Packet with stmt id
 */
 
 void mysql_stmt_reset(THD *thd, char *packet)
@@ -2504,9 +2489,11 @@ void mysql_stmt_reset(THD *thd, char *packet)
 }
 
 
-/*
+/**
   Delete a prepared statement from memory.
-  Note: we don't send any reply to this command.
+
+  @note
+    we don't send any reply to this command.
 */
 
 void mysql_stmt_close(THD *thd, char *packet)
@@ -2530,15 +2517,14 @@ void mysql_stmt_close(THD *thd, char *packet)
 }
 
 
-/*
+/**
   SQLCOM_DEALLOCATE implementation.
 
-  DESCRIPTION
     Close an SQL prepared statement. As this can be called from Dynamic
     SQL, we should be careful to not close a statement that is currently
     being executed.
 
-  RETURN VALUE
+  @return
     none: OK packet is sent in case of success, otherwise an error
     message is set in THD
 */
@@ -2561,21 +2547,18 @@ void mysql_sql_stmt_close(THD *thd)
     send_ok(thd);
 }
 
-/*
+/**
   Handle long data in pieces from client.
 
-  SYNOPSIS
-    mysql_stmt_get_longdata()
-      thd                Thread handle
-      packet             String to append
-      packet_length      Length of string (including end \0)
-
-  DESCRIPTION
     Get a part of a long data. To make the protocol efficient, we are
     not sending any return packets here. If something goes wrong, then
     we will send the error on 'execute' We assume that the client takes
     care of checking that all parts are sent to the server. (No checking
     that we get a 'end of column' in the server is performed).
+
+  @param thd                Thread handle
+  @param packet             String to append
+  @param packet_length      Length of string (including end \\0)
 */
 
 void mysql_stmt_get_longdata(THD *thd, char *packet, ulong packet_length)
@@ -2742,12 +2725,12 @@ void Prepared_statement::setup_set_params()
 }
 
 
-/*
-  DESCRIPTION
+/**
   Destroy this prepared statement, cleaning up all used memory
-    and resources. This is called from ::deallocate() to
-    handle COM_STMT_CLOSE and DEALLOCATE PREPARE or when
-    THD ends and all prepared statements are freed.
+  and resources.
+
+  This is called from ::deallocate() to handle COM_STMT_CLOSE and
+  DEALLOCATE PREPARE or when THD ends and all prepared statements are freed.
 */
 
 Prepared_statement::~Prepared_statement()
@@ -2804,28 +2787,24 @@ bool Prepared_statement::set_name(LEX_STRING *name_arg)
   global THD state management to the caller.
 ***************************************************************************/
 
-/*
+/**
   Parse statement text, validate the statement, and prepare it for execution.
 
-  SYNOPSIS
-    Prepared_statement::prepare()
-      packet             statement text
-      packet_len
-
-  DESCRIPTION
     You should not change global THD state in this function, if at all
     possible: it may be called from any context, e.g. when executing
     a COM_* command, and SQLCOM_* command, or a stored procedure.
 
-  NOTES
-      Precondition.
-      -------------
+  @param packet             statement text
+  @param packet_len
+
+  @note
+    Precondition:
     The caller must ensure that thd->change_list and thd->free_list
     is empty: this function will not back them up but will free
     in the end of its execution.
 
-      Postcondition.
-      --------------
+  @note
+    Postcondition:
     thd->mem_root contains unused memory allocated during validation.
 */
 
@@ -2956,28 +2935,25 @@ bool Prepared_statement::prepare(const char *packet, uint packet_len)
   DBUG_RETURN(error);
 }
 
-/*
+/**
   Execute a prepared statement.
 
-  SYNOPSIS
-    Prepared_statement::execute()
-      expanded_query     A query for binlogging which has all parameter
-                         markers ('?') replaced with their actual values.
-      open_cursor        True if an attempt to open a cursor should be made.
-                         Currenlty used only in the binary protocol.
-
-  DESCRIPTION
     You should not change global THD state in this function, if at all
     possible: it may be called from any context, e.g. when executing
     a COM_* command, and SQLCOM_* command, or a stored procedure.
 
-  NOTES
+  @param expanded_query     A query for binlogging which has all parameter
+                            markers ('?') replaced with their actual values.
+  @param open_cursor        True if an attempt to open a cursor should be made.
+                            Currenlty used only in the binary protocol.
+
+  @note
     Preconditions, postconditions.
-      ------------------------------
-      See the comment for Prepared_statement::prepare().
+    - See the comment for Prepared_statement::prepare().
 
-  RETURN
+  @retval
     FALSE	    ok
+  @retval
     TRUE		Error
 */
 
@@ -3161,7 +3137,7 @@ bool Prepared_statement::execute(String *expanded_query, bool open_cursor)
 }
 
 
-/* Common part of DEALLOCATE PREPARE and mysql_stmt_close */
+/** Common part of DEALLOCATE PREPARE and mysql_stmt_close. */
 
 bool Prepared_statement::deallocate()
 {

sql/sql_trigger.cc

@@ -168,7 +168,7 @@ static const LEX_STRING triggers_file_type=
 
 const char * const TRG_EXT= ".TRG";
 
-/*
+/**
   Table of .TRG file field descriptors.
   We have here only one field now because in nearest future .TRG
   files will be merged into .FRM files (so we don't need something
@@ -216,7 +216,7 @@ File_option sql_modes_parameters=
   FILE_OPTIONS_ULLLIST
 };
 
-/*
+/**
   This must be kept up to date whenever a new option is added to the list
   above, as it specifies the number of required parameters of the trigger in
   .trg file.
@@ -292,23 +292,27 @@ class Handle_old_incorrect_trigger_table_hook: public Unknown_key_hook
 };
 
 
-/*
+/**
   Create or drop trigger for table.
 
-  SYNOPSIS
-    mysql_create_or_drop_trigger()
-      thd    - current thread context (including trigger definition in LEX)
-      tables - table list containing one table for which trigger is created.
-      create - whenever we create (TRUE) or drop (FALSE) trigger
+  @param thd     current thread context (including trigger definition in LEX)
+  @param tables  table list containing one table for which trigger is created.
+  @param create  whenever we create (TRUE) or drop (FALSE) trigger
 
-  NOTE
+  @note
     This function is mainly responsible for opening and locking of table and
     invalidation of all its instances in table cache after trigger creation.
     Real work on trigger creation/dropping is done inside Table_triggers_list
     methods.
 
-  RETURN VALUE
+  @todo
+    TODO: We should check if user has TRIGGER privilege for table here.
+    Now we just require SUPER privilege for creating/dropping because
+    we don't have proper privilege checking for triggers in place yet.
+
+  @retval
     FALSE Success
+  @retval
     TRUE  error
 */
 bool mysql_create_or_drop_trigger(THD *thd, TABLE_LIST *tables, bool create)
@@ -479,19 +483,17 @@ bool mysql_create_or_drop_trigger(THD *thd, TABLE_LIST *tables, bool create)
 }
 
 
-/*
+/**
   Create trigger for table.
 
-  SYNOPSIS
-    create_trigger()
-      thd          - current thread context (including trigger definition in
+  @param thd           current thread context (including trigger definition in
                        LEX)
-      tables       - table list containing one open table for which the
+  @param tables        table list containing one open table for which the
                        trigger is created.
-      stmt_query   - [OUT] after successful return, this string contains
-                     well-formed statement for creating this trigger.
+  @param[out] stmt_query    after successful return, this string contains
+                            well-formed statement for creation this trigger.
 
-  NOTE
+  @note
     - Assumes that trigger name is fully qualified.
     - NULL-string means the following LEX_STRING instance:
     { str = 0; length = 0 }.
@@ -499,9 +501,10 @@ bool mysql_create_or_drop_trigger(THD *thd, TABLE_LIST *tables, bool create)
     simultaneously NULL-strings (non-SUID/old trigger) or valid strings
     (SUID/new trigger).
 
-  RETURN VALUE
-    False - success
-    True  - error
+  @retval
+    False   success
+  @retval
+    True    error
 */
 bool Table_triggers_list::create_trigger(THD *thd, TABLE_LIST *tables,
                                          String *stmt_query)
@@ -767,19 +770,18 @@ bool Table_triggers_list::create_trigger(THD *thd, TABLE_LIST *tables,
 }
 
 
-/*
-  Deletes the .TRG file for a table
+/**
+  Deletes the .TRG file for a table.
 
-  SYNOPSIS
-    rm_trigger_file()
-      path       - char buffer of size FN_REFLEN to be used
+  @param path         char buffer of size FN_REFLEN to be used
                       for constructing path to .TRG file.
-      db         - table's database name
-      table_name - table's name
+  @param db           table's database name
+  @param table_name   table's name
 
-  RETURN VALUE
-    False - success
-    True  - error
+  @retval
+    False   success
+  @retval
+    True    error
 */
 
 static bool rm_trigger_file(char *path, const char *db,
@@ -790,19 +792,18 @@ static bool rm_trigger_file(char *path, const char *db,
 }
 
 
-/*
-  Deletes the .TRN file for a trigger
+/**
+  Deletes the .TRN file for a trigger.
 
-  SYNOPSIS
-    rm_trigname_file()
-      path       - char buffer of size FN_REFLEN to be used
+  @param path         char buffer of size FN_REFLEN to be used
                       for constructing path to .TRN file.
-      db         - trigger's database name
-      table_name - trigger's name
+  @param db           trigger's database name
+  @param table_name   trigger's name
 
-  RETURN VALUE
-    False - success
-    True  - error
+  @retval
+    False   success
+  @retval
+    True    error
 */
 
 static bool rm_trigname_file(char *path, const char *db,
@@ -813,17 +814,16 @@ static bool rm_trigname_file(char *path, const char *db,
 }
 
 
-/*
+/**
   Helper function that saves .TRG file for Table_triggers_list object.
 
-  SYNOPSIS
-    save_trigger_file()
-      triggers    Table_triggers_list object for which file should be saved
-      db          Name of database for subject table
-      table_name  Name of subject table
+  @param triggers    Table_triggers_list object for which file should be saved
+  @param db          Name of database for subject table
+  @param table_name  Name of subject table
 
-  RETURN VALUE
+  @retval
     FALSE  Success
+  @retval
     TRUE   Error
 */
 
@@ -842,21 +842,26 @@ static bool save_trigger_file(Table_triggers_list *triggers, const char *db,
 }
 
 
-/*
+/**
   Drop trigger for table.
 
-  SYNOPSIS
-    drop_trigger()
-      thd         - current thread context
+  @param thd           current thread context
                        (including trigger definition in LEX)
-      tables      - table list containing one open table for which trigger
+  @param tables        table list containing one open table for which trigger
                        is dropped.
-      stmt_query  - [OUT] after successful return, this string contains
-                    well-formed statement for deleting this trigger.
+  @param[out] stmt_query    after successful return, this string contains
+                            well-formed statement for creation this trigger.
+
+  @todo
+    Probably instead of removing .TRG file we should move
+    to archive directory but this should be done as part of
+    parse_file.cc functionality (because we will need it
+    elsewhere).
 
-  RETURN VALUE
-    False - success
-    True  - error
+  @retval
+    False   success
+  @retval
+    True    error
 */
 bool Table_triggers_list::drop_trigger(THD *thd, TABLE_LIST *tables,
                                        String *stmt_query)
@@ -939,18 +944,17 @@ Table_triggers_list::~Table_triggers_list()
 }
 
 
-/*
+/**
   Prepare array of Field objects referencing to TABLE::record[1] instead
   of record[0] (they will represent OLD.* row values in ON UPDATE trigger
   and in ON DELETE trigger which will be called during REPLACE execution).
 
-  SYNOPSIS
-    prepare_record1_accessors()
-      table - pointer to TABLE object for which we are creating fields.
+  @param table   pointer to TABLE object for which we are creating fields.
 
-  RETURN VALUE
-    False - success
-    True  - error
+  @retval
+    False   success
+  @retval
+    True    error
 */
 bool Table_triggers_list::prepare_record1_accessors(TABLE *table)
 {
@@ -979,12 +983,10 @@ bool Table_triggers_list::prepare_record1_accessors(TABLE *table)
 }
 
 
-/*
+/**
   Adjust Table_triggers_list with new TABLE pointer.
 
-  SYNOPSIS
-    set_table()
-      new_table - new pointer to TABLE instance
+  @param new_table   new pointer to TABLE instance
 */
 
 void Table_triggers_list::set_table(TABLE *new_table)
@@ -998,20 +1000,26 @@ void Table_triggers_list::set_table(TABLE *new_table)
 }
 
 
-/*
+/**
   Check whenever .TRG file for table exist and load all triggers it contains.
 
-  SYNOPSIS
-    check_n_load()
-      thd        - current thread context
-      db         - table's database name
-      table_name - table's name
-      table      - pointer to table object
-      names_only - stop after loading trigger names
-
-  RETURN VALUE
-    False - success
-    True  - error
+  @param thd          current thread context
+  @param db           table's database name
+  @param table_name   table's name
+  @param table        pointer to table object
+  @param names_only   stop after loading trigger names
+
+  @todo
+    A lot of things to do here e.g. how about other funcs and being
+    more paranoical ?
+
+  @todo
+    This could be avoided if there is no triggers for UPDATE and DELETE.
+
+  @retval
+    False   success
+  @retval
+    True    error
 */
 
 bool Table_triggers_list::check_n_load(THD *thd, const char *db,
@@ -1394,24 +1402,23 @@ bool Table_triggers_list::check_n_load(THD *thd, const char *db,
 }
 
 
-/*
-  Obtains and returns trigger metadata
-
-  SYNOPSIS
-    get_trigger_info()
-      thd       - current thread context
-      event     - trigger event type
-      time_type - trigger action time
-      name      - returns name of trigger
-      stmt      - returns statement of trigger
-      sql_mode  - returns sql_mode of trigger
-      definer_user - returns definer/creator of trigger. The caller is
-                  responsible to allocate enough space for storing definer
-                  information.
-
-  RETURN VALUE
-    False - success
-    True  - error
+/**
+  Obtains and returns trigger metadata.
+
+  @param thd           current thread context
+  @param event         trigger event type
+  @param time_type     trigger action time
+  @param trigger_name  returns name of trigger
+  @param trigger_stmt  returns statement of trigger
+  @param sql_mode      returns sql_mode of trigger
+  @param definer       returns definer/creator of trigger. The caller is
+                       responsible to allocate enough space for storing
+                       definer information.
+
+  @retval
+    False   success
+  @retval
+    True    error
 */
 
 bool Table_triggers_list::get_trigger_info(THD *thd, trg_event_type event,
@@ -1577,21 +1584,20 @@ bool add_table_for_trigger(THD *thd,
 }
 
 
-/*
+/**
   Drop all triggers for table.
 
-  SYNOPSIS
-    drop_all_triggers()
-      thd    - current thread context
-      db     - schema for table
-      name   - name for table
+  @param thd      current thread context
+  @param db       schema for table
+  @param name     name for table
 
-  NOTE
+  @note
     The calling thread should hold the LOCK_open mutex;
 
-  RETURN VALUE
-    False - success
-    True  - error
+  @retval
+    False   success
+  @retval
+    True    error
 */
 
 bool Table_triggers_list::drop_all_triggers(THD *thd, char *db, char *name)
@@ -1641,19 +1647,18 @@ bool Table_triggers_list::drop_all_triggers(THD *thd, char *db, char *name)
 }
 
 
-/*
+/**
   Update .TRG file after renaming triggers' subject table
   (change name of table in triggers' definitions).
 
-  SYNOPSIS
-    change_table_name_in_triggers()
-      thd                 Thread context
-      db_name             Database of subject table
-      old_table_name      Old subject table's name
-      new_table_name      New subject table's name
+  @param thd                 Thread context
+  @param db_name             Database of subject table
+  @param old_table_name      Old subject table's name
+  @param new_table_name      New subject table's name
 
-  RETURN VALUE
+  @retval
     FALSE  Success
+  @retval
     TRUE   Failure
 */
 
@@ -1723,19 +1728,18 @@ Table_triggers_list::change_table_name_in_triggers(THD *thd,
 }
 
 
-/*
-  Iterate though Table_triggers_list::names_list list and update .TRN files
-  after renaming triggers' subject table.
-
-  SYNOPSIS
-    change_table_name_in_trignames()
-      db_name             Database of subject table
-      new_table_name      New subject table's name
-      stopper             Pointer to Table_triggers_list::names_list at
+/**
+  Iterate though Table_triggers_list::names_list list and update
+  .TRN files after renaming triggers' subject table.
+
+  @param db_name             Database of subject table
+  @param new_table_name      New subject table's name
+  @param stopper             Pointer to Table_triggers_list::names_list at
                              which we should stop updating.
 
-  RETURN VALUE
+  @retval
     0      Success
+  @retval
     non-0  Failure, pointer to Table_triggers_list::names_list element
     for which update failed.
 */
@@ -1771,7 +1775,7 @@ Table_triggers_list::change_table_name_in_trignames(const char *db_name,
 
 
 /**
-  @brief Update .TRG and .TRN files after renaming triggers' subject table.
+  Update .TRG and .TRN files after renaming triggers' subject table.
 
   @param[in,out] thd Thread context
   @param[in] db Old database of subject table
@@ -1933,19 +1937,17 @@ bool Table_triggers_list::process_triggers(THD *thd,
 }
 
 
-/*
-  Mark fields of subject table which we read/set in its triggers as such.
-
-  SYNOPSIS
-    mark_fields_used()
-      thd    Current thread context
-      event  Type of event triggers for which we are going to ins
+/**
+  Mark fields of subject table which we read/set in its triggers
+  as such.
 
-  DESCRIPTION
   This method marks fields of subject table which are read/set in its
   triggers as such (by properly updating TABLE::read_set/write_set)
   and thus informs handler that values for these fields should be
   retrieved/stored during execution of statement.
+
+  @param thd    Current thread context
+  @param event  Type of event triggers for which we are going to inspect
 */
 
 void Table_triggers_list::mark_fields_used(trg_event_type event)
@@ -1971,23 +1973,23 @@ void Table_triggers_list::mark_fields_used(trg_event_type event)
 }
 
 
-/*
-  Trigger BUG#14090 compatibility hook
+/**
+  Trigger BUG#14090 compatibility hook.
 
-  SYNOPSIS
-    Handle_old_incorrect_sql_modes_hook::process_unknown_string()
-    unknown_key          [in/out] reference on the line with unknown
+  @param[in,out] unknown_key       reference on the line with unknown
     parameter and the parsing point
-    base                 [in] base address for parameter writing (structure
-                              like TABLE)
-    mem_root             [in] MEM_ROOT for parameters allocation
-    end                  [in] the end of the configuration
+  @param[in]     base              base address for parameter writing
+    (structure like TABLE)
+  @param[in]     mem_root          MEM_ROOT for parameters allocation
+  @param[in]     end               the end of the configuration
 
+  @note
     NOTE: this hook process back compatibility for incorrectly written
     sql_modes parameter (see BUG#14090).
 
-  RETURN
+  @retval
     FALSE OK
+  @retval
     TRUE  Error
 */
 
@@ -2029,13 +2031,12 @@ Handle_old_incorrect_sql_modes_hook::process_unknown_string(char *&unknown_key,
   DBUG_RETURN(FALSE);
 }
 
-/*
+#define INVALID_TRIGGER_TABLE_LENGTH 15
+
+/**
   Trigger BUG#15921 compatibility hook. For details see
   Handle_old_incorrect_sql_modes_hook::process_unknown_string().
 */
-
-#define INVALID_TRIGGER_TABLE_LENGTH 15
-
 bool
 Handle_old_incorrect_trigger_table_hook::
 process_unknown_string(char *&unknown_key, uchar* base, MEM_ROOT *mem_root,
@@ -2074,9 +2075,9 @@ process_unknown_string(char *&unknown_key, uchar* base, MEM_ROOT *mem_root,
 /**
   Contruct path to TRN-file.
 
-  @param[in]  thd        Thread context.
-  @param[in]  trg_name   Trigger name.
-  @param[out] trn_path   Variable to store constructed path
+  @param thd[in]        Thread context.
+  @param trg_name[in]   Trigger name.
+  @param trn_path[out]  Variable to store constructed path
 */
 
 void build_trn_path(THD *thd, const sp_name *trg_name, LEX_STRING *trn_path)
@@ -2109,10 +2110,10 @@ bool check_trn_exists(const LEX_STRING *trn_path)
 /**
   Retrieve table name for given trigger.
 
-  @param[in]  thd        Thread context.
-  @param[in]  trg_name   Trigger name.
-  @param[in]  trn_path   Path to the corresponding TRN-file.
-  @param[out] tbl_name  Variable to store retrieved table name.
+  @param thd[in]        Thread context.
+  @param trg_name[in]   Trigger name.
+  @param trn_path[in]   Path to the corresponding TRN-file.
+  @param tbl_name[out]  Variable to store retrieved table name.
 
   @return Error status.
     @retval FALSE on success.

sql/sql_update.cc

@@ -84,7 +84,7 @@ static bool check_fields(THD *thd, List<Item> &items)
 
 
 /**
-  @brief Re-read record if more columns are needed for error message.
+  Re-read record if more columns are needed for error message.
 
   If we got a duplicate key error, we want to write an error
   message containing the value of the duplicate key. If we do not have

sql/sql_view.cc

@@ -206,7 +206,7 @@ fill_defined_view_parts (THD *thd, TABLE_LIST *view)
 
 
 /**
-  @brief Creating/altering VIEW procedure
+  Creating/altering VIEW procedure
 
   @param thd thread handler
   @param views views to create