Doxygenized comments.

2d615a61 · cmiller@zippy.cornsilk.net · 91b5c119 · 2d615a61 · 2d615a61 · 2d615a61
Commit 2d615a61 authored Oct 11, 2007 by cmiller@zippy.cornsilk.net
11 changed files
--- a/sql/net_serv.cc
+++ b/sql/net_serv.cc
@@ -13,15 +13,16 @@
   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 is the net layer API for the MySQL client/server protocol,
  which is a tightly coupled, proprietary protocol owned by MySQL AB.
+  @note
  Any re-implementations of this protocol must also be under GPL
  unless one has got an license from MySQL AB stating otherwise.
-*/
-/*
+  Write and read of logical packets to/from socket.
-  Write and read of logical packets to/from socket
  Writes are cached into net_buffer_length big packets.
  Read packets are reallocated dynamicly when reading big packets.
@@ -111,7 +112,7 @@ extern void query_cache_insert(NET *net, const char *packet, ulong length);
 static my_bool net_write_buff(NET *net,const uchar *packet,ulong len);
-	/* Init with packet info */
+/** Init with packet info. */
 my_bool my_net_init(NET *net, Vio* vio)
 {
@@ -163,7 +164,7 @@ void net_end(NET *net)
 }
-/* Realloc the packet buffer */
+/** Realloc the packet buffer. */
 my_bool net_realloc(NET *net, size_t length)
 {
@@ -201,19 +202,16 @@ my_bool net_realloc(NET *net, size_t length)
 }
-/*
+/**
-  Check if there is any data to be read from the socket
-  SYNOPSIS
-    net_data_is_ready()
-    sd   socket descriptor
-  DESCRIPTION
  Check if there is any data to be read from the socket.
-  RETURN VALUES
+  @param sd   socket descriptor
+  @retval
    0  No data to read
+  @retval
    1  Data or EOF to read
+  @retval
    -1   Don't know if data is ready or not
 */
@@ -258,16 +256,10 @@ static int net_data_is_ready(my_socket sd)
 #endif /* EMBEDDED_LIBRARY */
-/*
+/**
  Remove unwanted characters from connection
-  and check if disconnected
+  and check if disconnected.
-  SYNOPSIS
-    net_clear()
-    net			NET handler
-    clear_buffer	If <> 0, then clear all data from communication buffer
-  DESCRIPTION
    Read from socket until there is nothing more to read. Discard
    what is read.
@@ -278,6 +270,8 @@ static int net_data_is_ready(my_socket sd)
    a FIN packet), then select() considers a socket "ready to read",
    in the sense that there's EOF to read, but read() returns 0.
+  @param net			NET handler
+  @param clear_buffer           if <> 0, then clear all data from comm buff
 */
 void net_clear(NET *net, my_bool clear_buffer)
@@ -335,7 +329,7 @@ void net_clear(NET *net, my_bool clear_buffer)
 }
-	/* Flush write_buffer if not empty. */
+/** Flush write_buffer if not empty. */
 my_bool net_flush(NET *net)
 {
@@ -358,12 +352,13 @@ my_bool net_flush(NET *net)
 ** Write something to server/client buffer
 *****************************************************************************/
-/*
+/**
-  Write a logical packet with packet header
+  Write a logical packet with packet header.
  Format: Packet length (3 bytes), packet number(1 byte)
  When compression is used a 3 byte compression length is added
-  NOTE
+  @note
    If compression is used the original package is modified!
 */
@@ -400,19 +395,9 @@ my_net_write(NET *net,const uchar *packet,size_t len)
  return test(net_write_buff(net,packet,len));
 }
-/*
+/**
  Send a command to the server.
-  SYNOPSIS
-    net_write_command()
-    net			NET handler
-    command		Command in MySQL server (enum enum_server_command)
-    header		Header to write after command
-    head_len		Length of header
-    packet		Query or parameter to query
-    len			Length of packet
-  DESCRIPTION
    The reason for having both header and packet is so that libmysql
    can easy add a header to a special command (like prepared statements)
    without having to re-alloc the string.
@@ -420,11 +405,20 @@ my_net_write(NET *net,const uchar *packet,size_t len)
    As the command is part of the first data packet, we have to do some data
    juggling to put the command in there, without having to create a new
    packet.
    This function will split big packets into sub-packets if needed.
    (Each sub packet can only be 2^24 bytes)
-  RETURN VALUES
+  @param net		NET handler
+  @param command	Command in MySQL server (enum enum_server_command)
+  @param header	Header to write after command
+  @param head_len	Length of header
+  @param packet	Query or parameter to query
+  @param len		Length of packet
+  @retval
    0	ok
+  @retval
    1	error
 */
@@ -468,16 +462,9 @@ net_write_command(NET *net,uchar command,
                   net_write_buff(net, packet, len) || net_flush(net)));
 }
-/*
+/**
  Caching the data in a local buffer before sending it.
-  SYNOPSIS
-    net_write_buff()
-    net		Network handler
-    packet	Packet to send
-    len		Length of packet
-  DESCRIPTION
   Fill up net->buffer and send it to the client when full.
    If the rest of the to-be-sent-packet is bigger than buffer,
@@ -485,15 +472,19 @@ net_write_command(NET *net,uchar command,
    If not, copy the rest of the data to the buffer and return without
    sending data.
-  NOTES
+  @param net		Network handler
-    The cached buffer can be sent as it is with 'net_flush()'.
+  @param packet	Packet to send
+  @param len		Length of packet
+  @note
+    The cached buffer can be sent as it is with 'net_flush()'.
    In this code we have to be careful to not send a packet longer than
    MAX_PACKET_LENGTH to net_real_write() if we are using the compressed
    protocol as we store the length of the compressed packet in 3 bytes.
-  RETURN
+  @retval
    0	ok
+  @retval
    1
 */
@@ -547,9 +538,12 @@ net_write_buff(NET *net, const uchar *packet, ulong len)
 }
-/*
+/**
  Read and write one packet using timeouts.
  If needed, the packet is compressed before sending.
+  @todo
+    - TODO is it needed to set this variable if we have no socket
 */
 int
@@ -726,18 +720,17 @@ static my_bool net_safe_read(NET *net, uchar *buff, size_t length,
  return 0;
 }
-/*
+/**
  Help function to clear the commuication buffer when we get a too big packet.
-  SYNOPSIS
+  @param net		Communication handle
-    my_net_skip_rest()
+  @param remain	Bytes to read
-    net		Communication handle
+  @param alarmed	Parameter for thr_alarm()
-    remain	Bytes to read
+  @param alarm_buff	Parameter for thr_alarm()
-    alarmed	Parameter for thr_alarm()
-    alarm_buff	Parameter for thr_alarm()
-  RETURN VALUES
+  @retval
   0	Was able to read the whole packet
+  @retval
   1	Got mailformed packet from client
 */
@@ -780,10 +773,13 @@ static my_bool my_net_skip_rest(NET *net, uint32 remain, thr_alarm_t *alarmed,
 #endif /* NO_ALARM */
-/*
+/**
-  Reads one packet to net->buff + net->where_b
+  Reads one packet to net->buff + net->where_b.
-  Returns length of packet.  Long packets are handled by my_net_read().
+  Long packets are handled by my_net_read().
  This function reallocates the net->buff buffer if necessary.
+  @return
+    Returns length of packet.
 */
 static ulong
@@ -972,15 +968,18 @@ my_real_read(NET *net, size_t *complen)
 }
-/*
+/**
  Read a packet from the client/server and return it without the internal
  package header.
  If the packet is the first packet of a multi-packet packet
  (which is indicated by the length of the packet = 0xffffff) then
  all sub packets are read and concatenated.
  If the packet was compressed, its uncompressed and the length of the
  uncompressed packet is returned.
+  @return
  The function returns the length of the found packet or packet_error.
  net->read_pos points to the read data.
 */

--- a/sql/nt_servc.cc
+++ b/sql/nt_servc.cc
-/* ------------------------------------------------------------------------
+/**
-   Windows NT Service class library
+  @file
+  @brief
+  Windows NT Service class library.
  Copyright Abandoned 1998 Irena Pancirov - Irnet Snc
  This file is public domain and comes with NO WARRANTY of any kind
- -------------------------------------------------------------------------- */
+*/
 #include <windows.h>
 #include <process.h>
 #include <stdio.h>
@@ -73,12 +77,13 @@ BOOL NTService::GetOS()
 }
-/* ------------------------------------------------------------------------
+/**
- Init()  Registers the main service thread with the service manager
+  Registers the main service thread with the service manager.
-    ServiceThread - pointer to the main programs entry function
+  @param ServiceThread  pointer to the main programs entry function
                        when the service is started
- -------------------------------------------------------------------------- */
+*/
 long NTService::Init(LPCSTR szInternName,void *ServiceThread)
 {
@@ -99,13 +104,15 @@ long NTService::Init(LPCSTR szInternName,void *ServiceThread)
 }
-/* ------------------------------------------------------------------------
+/**
-  Install() - Installs the service with Service manager
+  Installs the service with Service manager.
  nError values:
-	0  success
+  - 0  success
-	1  Can't open the Service manager
+  - 1  Can't open the Service manager
-	2  Failed to create service
+  - 2  Failed to create service.
- -------------------------------------------------------------------------- */
+*/
 BOOL NTService::Install(int startType, LPCSTR szInternName,
 			LPCSTR szDisplayName,
@@ -155,14 +162,16 @@ BOOL NTService::Install(int startType, LPCSTR szInternName,
 }
-/* ------------------------------------------------------------------------
+/**
-  Remove() - Removes  the service
+  Removes  the service.
  nError values:
-	0  success
+  - 0  success
-	1  Can't open the Service manager
+  - 1  Can't open the Service manager
-	2  Failed to locate service
+  - 2  Failed to locate service
-	3  Failed to delete service
+  - 3  Failed to delete service.
- -------------------------------------------------------------------------- */
+*/
 BOOL NTService::Remove(LPCSTR szInternName)
 {
@@ -199,10 +208,10 @@ BOOL NTService::Remove(LPCSTR szInternName)
  return ret_value;
 }
-/* ------------------------------------------------------------------------
+/**
-   Stop() - this function should be called before the app. exits to stop
+  this function should be called before the app. exits to stop
  the service
- -------------------------------------------------------------------------- */
+*/
 void NTService::Stop(void)
 {
  SetStatus(SERVICE_STOP_PENDING,NO_ERROR, 0, 1, 60000);
@@ -210,10 +219,11 @@ void NTService::Stop(void)
  SetStatus(SERVICE_STOPPED, NO_ERROR, 0, 1, 1000);
 }
-/* ------------------------------------------------------------------------
+/**
-  ServiceMain() - This is the function that is called from the
+  This is the function that is called from the
-		  service manager to start the service
+  service manager to start the service.
- -------------------------------------------------------------------------- */
+*/
 void NTService::ServiceMain(DWORD argc, LPTSTR *argv)
 {
@@ -264,9 +274,9 @@ void NTService::ServiceMain(DWORD argc, LPTSTR *argv)
  return;
 }
-/* ------------------------------------------------------------------------
+/**
-   StartService() - starts the appliaction thread
+  starts the appliaction thread.
- -------------------------------------------------------------------------- */
+*/
 BOOL NTService::StartService()
 {

--- a/sql/opt_sum.cc
+++ b/sql/opt_sum.cc
@@ -14,7 +14,9 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
-/*
+/**
+  @file
  Optimising of MIN(), MAX() and COUNT(*) queries without 'group by' clause
  by replacing the aggregate expression with a constant.  
@@ -22,6 +24,7 @@
  types of queries are optimised (assuming the table handler supports
  the required methods)
+  @verbatim
  SELECT COUNT(*) FROM t1[,t2,t3,...]
  SELECT MIN(b) FROM t1 WHERE a=const
  SELECT MAX(c) FROM t1 WHERE a=const AND b=const
@@ -29,6 +32,7 @@
  SELECT MIN(b) FROM t1 WHERE a=const AND b>const
  SELECT MIN(b) FROM t1 WHERE a=const AND b BETWEEN const AND const
  SELECT MAX(b) FROM t1 WHERE a=const AND b BETWEEN const AND const
+  @endverbatim
  Instead of '<' one can use '<=', '>', '>=' and '=' as well.
  Instead of 'a=const' the condition 'a IS NULL' can be used.
@@ -36,10 +40,11 @@
  If all selected fields are replaced then we will also remove all
  involved tables and return the answer without any join. Thus, the
  following query will be replaced with a row of two constants:
+  @verbatim
  SELECT MAX(b), MIN(d) FROM t1,t2 
    WHERE a=const AND b<const AND d>const
+  @endverbatim
  (assuming a index for column d of table t2 is defined)
 */
 #include "mysql_priv.h"
@@ -83,25 +88,25 @@ static ulonglong get_exact_record_count(TABLE_LIST *tables)
 }
-/*
+/**
  Substitutes constants for some COUNT(), MIN() and MAX() functions.
-  SYNOPSIS
+  @param tables                list of leaves of join table tree
-    opt_sum_query()
+  @param all_fields            All fields to be returned
-    tables                list of leaves of join table tree
+  @param conds                 WHERE clause
-    all_fields            All fields to be returned
-    conds                 WHERE clause
-  NOTE:
+  @note
    This function is only called for queries with sum functions and no
    GROUP BY part.
-  RETURN VALUES
+  @retval
    0                    no errors
+  @retval
    1                    if all items were resolved
+  @retval
    HA_ERR_KEY_NOT_FOUND on impossible conditions
-    OR an error number from my_base.h HA_ERR_... if a deadlock or a lock
+  @retval
-       wait timeout happens, for example
+    HA_ERR_... if a deadlock or a lock wait timeout happens, for example
 */
 int opt_sum_query(TABLE_LIST *tables, List<Item> &all_fields,COND *conds)
@@ -472,19 +477,18 @@ int opt_sum_query(TABLE_LIST *tables, List<Item> &all_fields,COND *conds)
 }
-/*
+/**
-  Test if the predicate compares a field with constants
+  Test if the predicate compares a field with constants.
-  SYNOPSIS
+  @param func_item        Predicate item
-    simple_pred()
+  @param[out] args        Here we store the field followed by constants
-    func_item        Predicate item
+  @param[out] inv_order   Is set to 1 if the predicate is of the form
-    args        out: Here we store the field followed by constants
-    inv_order   out: Is set to 1 if the predicate is of the form
                          'const op field'
-  RETURN
+  @retval
    0        func_item is a simple predicate: a field is compared with
    constants
+  @retval
    1        Otherwise
 */
@@ -556,22 +560,9 @@ bool simple_pred(Item_func *func_item, Item **args, bool *inv_order)
 }
-/* 
+/**
-   Check whether a condition matches a key to get {MAX|MIN}(field):
+  Check whether a condition matches a key to get {MAX|MIN}(field):.
-   SYNOPSIS
-     matching_cond()
-     max_fl         in:     Set to 1 if we are optimising MAX()              
-     ref            in/out: Reference to the structure we store the key value
-     keyinfo        in      Reference to the key info
-     field_part     in:     Pointer to the key part for the field
-     cond           in      WHERE condition
-     key_part_used  in/out: Map of matchings parts
-     range_fl       in/out: Says whether including key will be used
-     prefix_len     out:    Length of common key part for the range
-                            where MAX/MIN is searched for
-   DESCRIPTION
     For the index specified by the keyinfo parameter, index that
     contains field as its component (field_part), the function
     checks whether the condition cond is a conjunction and all its
@@ -582,8 +573,20 @@ bool simple_pred(Item_func *func_item, Item **args, bool *inv_order)
     - field {<|<=|>=|>|=} const or const {<|<=|>=|>|=} field
     - field between const1 and const2
-  RETURN
+  @param[in]     max_fl         Set to 1 if we are optimising MAX()
+  @param[in,out] ref            Reference to the structure we store the key
+    value
+  @param[in]     keyinfo        Reference to the key info
+  @param[in]     field_part     Pointer to the key part for the field
+  @param[in]     cond           WHERE condition
+  @param[in,out] key_part_used  Map of matchings parts
+  @param[in,out] range_fl       Says whether including key will be used
+  @param[out]    prefix_len     Length of common key part for the range
+    where MAX/MIN is searched for
+  @retval
    0        Index can't be used.
+  @retval
    1        We can use index to get MIN/MAX value
 */
@@ -748,31 +751,21 @@ static bool matching_cond(bool max_fl, TABLE_REF *ref, KEY *keyinfo,
 }
-/*
+/**
  Check whether we can get value for {max|min}(field) by using a key.
-  SYNOPSIS
+     If where-condition is not a conjunction of 0 or more conjuct the
-    find_key_for_maxmin()
-    max_fl      in:     0 for MIN(field) / 1 for MAX(field)
-    ref         in/out  Reference to the structure we store the key value
-    field       in:     Field used inside MIN() / MAX()
-    cond        in:     WHERE condition
-    range_fl    out:    Bit flags for how to search if key is ok
-    prefix_len  out:    Length of prefix for the search range
-  DESCRIPTION
-    If where condition is not a conjunction of 0 or more conjuct the
     function returns false, otherwise it checks whether there is an
     index including field as its k-th component/part such that:
-     1. for each previous component f_i there is one and only one conjunct
+     -# for each previous component f_i there is one and only one conjunct
        of the form: f_i= const_i or const_i= f_i or f_i is null
-     2. references to field occur only in conjucts of the form:
+     -# references to field occur only in conjucts of the form:
        field {<|<=|>=|>|=} const or const {<|<=|>=|>|=} field or 
        field BETWEEN const1 AND const2
-     3. all references to the columns from the same table as column field
+     -# all references to the columns from the same table as column field
        occur only in conjucts mentioned above.
-     4. each of k first components the index is not partial, i.e. is not
+     -# each of k first components the index is not partial, i.e. is not
        defined on a fixed length proper prefix of the field.
     If such an index exists the function through the ref parameter
@@ -782,16 +775,25 @@ static bool matching_cond(bool max_fl, TABLE_REF *ref, KEY *keyinfo,
     (if we have a condition field = const, prefix_len contains the length
     of the whole search key)
-  NOTE
+  @param[in]     max_fl      0 for MIN(field) / 1 for MAX(field)
+  @param[in,out] ref         Reference to the structure we store the key value
+  @param[in]     field       Field used inside MIN() / MAX()
+  @param[in]     cond        WHERE condition
+  @param[out]    range_fl    Bit flags for how to search if key is ok
+  @param[out]    prefix_len  Length of prefix for the search range
+  @note
    This function may set table->key_read to 1, which must be reset after
    index is used! (This can only happen when function returns 1)
-  RETURN
+  @retval
    0   Index can not be used to optimize MIN(field)/MAX(field)
-    1   Can use key to optimize MIN()/MAX()
+  @retval
+    1   Can use key to optimize MIN()/MAX().
    In this case ref, range_fl and prefix_len are updated
 */
 static bool find_key_for_maxmin(bool max_fl, TABLE_REF *ref,
                                Field* field, COND *cond,
                                uint *range_fl, uint *prefix_len)
@@ -883,20 +885,19 @@ static bool find_key_for_maxmin(bool max_fl, TABLE_REF *ref,
 }
-/*
+/**
-  Check whether found key is in range specified by conditions
+  Check whether found key is in range specified by conditions.
-  SYNOPSIS
+  @param[in] max_fl         0 for MIN(field) / 1 for MAX(field)
-    reckey_in_range()
+  @param[in] ref            Reference to the key value and info
-    max_fl      in:     0 for MIN(field) / 1 for MAX(field)
+  @param[in] field          Field used the MIN/MAX expression
-    ref         in:     Reference to the key value and info
+  @param[in] cond           WHERE condition
-    field       in:     Field used the MIN/MAX expression
+  @param[in] range_fl       Says whether there is a condition to to be checked
-    cond        in:     WHERE condition
+  @param[in] prefix_len     Length of the constant part of the key
-    range_fl    in:     Says whether there is a condition to to be checked
-    prefix_len  in:     Length of the constant part of the key
-  RETURN
+  @retval
    0        ok
+  @retval
    1        WHERE was not true for the found row
 */
@@ -911,16 +912,16 @@ static int reckey_in_range(bool max_fl, TABLE_REF *ref, Field* field,
 }
-/*
+/**
-  Check whether {MAX|MIN}(field) is in range specified by conditions
+  Check whether {MAX|MIN}(field) is in range specified by conditions.
-  SYNOPSIS
-    maxmin_in_range()
-    max_fl      in:     0 for MIN(field) / 1 for MAX(field)
-    field       in:     Field used the MIN/MAX expression
-    cond        in:     WHERE condition
-  RETURN
+  @param[in] max_fl          0 for MIN(field) / 1 for MAX(field)
+  @param[in] field           Field used the MIN/MAX expression
+  @param[in] cond            WHERE condition
+  @retval
    0        ok
+  @retval
    1        WHERE was not true for the found row
 */

--- a/sql/parse_file.cc
+++ b/sql/parse_file.cc
@@ -13,7 +13,12 @@
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
-// Text .frm files management routines
+/**
+  @file
+  @brief
+  Text .frm files management routines
+*/
 #include "mysql_priv.h"
 #include <errno.h>
@@ -22,17 +27,16 @@
 #include <my_dir.h>
-/*
+/**
-  write string with escaping
+  Write string with escaping.
-  SYNOPSIS
+  @param file	  IO_CACHE for record
-    write_escaped_string()
+  @param val_s	  string for writing
-    file	- IO_CACHE for record
-    val_s	- string for writing
-  RETURN
+  @retval
-    FALSE - OK
+    FALSE   OK
-    TRUE  - error
+  @retval
+    TRUE    error
 */
 static my_bool
@@ -77,21 +81,21 @@ write_escaped_string(IO_CACHE *file, LEX_STRING *val_s)
 }
-/*
+/**
-  write parameter value to IO_CACHE
+  Write parameter value to IO_CACHE.
-  SYNOPSIS
+  @param file          pointer to IO_CACHE structure for writing
-    write_parameter()
+  @param base          pointer to data structure
-    file	pointer to IO_CACHE structure for writing
+  @param parameter     pointer to parameter descriptor
-    base	pointer to data structure
+  @param old_version   for returning back old version number value
-    parameter	pointer to parameter descriptor
-    old_version	for returning back old version number value
-  RETURN
+  @retval
-    FALSE - OK
+    FALSE   OK
-    TRUE  - error
+  @retval
+    TRUE    error
 */
 static my_bool
 write_parameter(IO_CACHE *file, uchar* base, File_option *parameter,
 		ulonglong *old_version)
@@ -191,24 +195,24 @@ write_parameter(IO_CACHE *file, uchar* base, File_option *parameter,
 }
-/*
+/**
-  write new .frm
+  Write new .frm.
-  SYNOPSIS
+  @param dir           directory where put .frm
-    sql_create_definition_file()
+  @param file_name     .frm file name
-    dir			directory where put .frm
+  @param type          .frm type string (VIEW, TABLE)
-    file		.frm file name
+  @param base          base address for parameter reading (structure like
-    type		.frm type string (VIEW, TABLE)
-    base		base address for parameter reading (structure like
                       TABLE)
-    parameters		parameters description
+  @param parameters    parameters description
-    max_versions	number of versions to save
+  @param max_versions  number of versions to save
-  RETURN
+  @retval
-    FALSE - OK
+    FALSE   OK
-    TRUE - error
+  @retval
+    TRUE    error
 */
 my_bool
 sql_create_definition_file(const LEX_STRING *dir, const LEX_STRING *file_name,
 			   const LEX_STRING *type,
@@ -345,21 +349,19 @@ sql_create_definition_file(const LEX_STRING *dir, const LEX_STRING *file_name,
  DBUG_RETURN(TRUE);
 }
-/*
+/**
-  Renames a frm file (including backups) in same schema
+  Renames a frm file (including backups) in same schema.
-  SYNOPSIS
-    rename_in_schema_file
-    schema            name of given schema           
-    old_name          original file name
-    new_name          new file name
-    revision          revision number
-    num_view_backups  number of backups
-  RETURN
+  @param schema            name of given schema
-    0 - OK 
+  @param old_name          original file name
-    1 - Error (only if renaming of frm failed)
+  @param new_name          new file name
+  @param revision          revision number
+  @param num_view_backups  number of backups
+  @retval
+    0   OK
+  @retval
+    1   Error (only if renaming of frm failed)
 */
 my_bool rename_in_schema_file(const char *schema, const char *old_name, 
                              const char *new_name, ulonglong revision, 
@@ -401,21 +403,20 @@ my_bool rename_in_schema_file(const char *schema, const char *old_name,
  return 0;
 }
-/*
+/**
-  Prepare frm to parse (read to memory)
+  Prepare frm to parse (read to memory).
-  SYNOPSIS
+  @param file_name		  path & filename to .frm file
-    sql_parse_prepare()
+  @param mem_root		  MEM_ROOT for buffer allocation
-    file_name		- path & filename to .frm file
+  @param bad_format_errors	  send errors on bad content
-    mem_root		- MEM_ROOT for buffer allocation
-    bad_format_errors	- send errors on bad content
-  RETURN
+  @note
+    returned pointer + 1 will be type of .frm
+  @return
    0 - error
+  @return
    parser object
-  NOTE
-    returned pointer + 1 will be type of .frm
 */
 File_parser * 
@@ -506,22 +507,22 @@ sql_parse_prepare(const LEX_STRING *file_name, MEM_ROOT *mem_root,
 }
-/*
+/**
-  parse LEX_STRING
+  parse LEX_STRING.
-  SYNOPSIS
+  @param ptr		  pointer on string beginning
-    parse_string()
+  @param end		  pointer on symbol after parsed string end (still owned
-    ptr		- pointer on string beginning
-    end		- pointer on symbol after parsed string end (still owned
                         by buffer and can be accessed
-    mem_root	- MEM_ROOT for parameter allocation
+  @param mem_root	  MEM_ROOT for parameter allocation
-    str		- pointer on string, where results should be stored
+  @param str		  pointer on string, where results should be stored
-  RETURN
+  @retval
-    0	- error
+    0	  error
-    #	- pointer on symbol after string
+  @retval
+    \#	  pointer on symbol after string
 */
 static char *
 parse_string(char *ptr, char *end, MEM_ROOT *mem_root, LEX_STRING *str)
 {
@@ -539,18 +540,17 @@ parse_string(char *ptr, char *end, MEM_ROOT *mem_root, LEX_STRING *str)
 }
-/*
+/**
-  read escaped string from ptr to eol in already allocated str
+  read escaped string from ptr to eol in already allocated str.
-  SYNOPSIS
+  @param ptr		  pointer on string beginning
-    read_escaped_string()
+  @param eol		  pointer on character after end of string
-    ptr		- pointer on string beginning
+  @param str		  target string
-    eol		- pointer on character after end of string
-    str		- target string
-  RETURN
+  @retval
-    FALSE - OK
+    FALSE   OK
-    TRUE  - error
+  @retval
+    TRUE    error
 */
 my_bool
@@ -598,22 +598,22 @@ read_escaped_string(char *ptr, char *eol, LEX_STRING *str)
 }
-/*
+/**
-  parse \n delimited escaped string
+  parse \\n delimited escaped string.
-  SYNOPSIS
+  @param ptr		  pointer on string beginning
-    parse_escaped_string()
+  @param end		  pointer on symbol after parsed string end (still owned
-    ptr		- pointer on string beginning
-    end		- pointer on symbol after parsed string end (still owned
                         by buffer and can be accessed
-    mem_root	- MEM_ROOT for parameter allocation
+  @param mem_root	  MEM_ROOT for parameter allocation
-    str		- pointer on string, where results should be stored
+  @param str		  pointer on string, where results should be stored
-  RETURN
+  @retval
-    0	- error
+    0	  error
-    #	- pointer on symbol after string
+  @retval
+    \#	  pointer on symbol after string
 */
 char *
 parse_escaped_string(char *ptr, char *end, MEM_ROOT *mem_root, LEX_STRING *str)
 {
@@ -628,20 +628,19 @@ parse_escaped_string(char *ptr, char *end, MEM_ROOT *mem_root, LEX_STRING *str)
 }
-/*
+/**
-  parse '' delimited escaped string
+  parse '' delimited escaped string.
-  SYNOPSIS
+  @param ptr		  pointer on string beginning
-    parse_quoted_escaped_string()
+  @param end		  pointer on symbol after parsed string end (still owned
-    ptr		- pointer on string beginning
-    end		- pointer on symbol after parsed string end (still owned
                         by buffer and can be accessed
-    mem_root	- MEM_ROOT for parameter allocation
+  @param mem_root	  MEM_ROOT for parameter allocation
-    str		- pointer on string, where results should be stored
+  @param str		  pointer on string, where results should be stored
-  RETURN
+  @retval
-    0	- error
+    0	  error
-    #	- pointer on symbol after string
+  @retval
+    \#	  pointer on symbol after string
 */
 static char *
@@ -673,18 +672,16 @@ parse_quoted_escaped_string(char *ptr, char *end,
 }
-/*
+/**
  Parser for FILE_OPTIONS_ULLLIST type value.
-  SYNOPSIS
+  @param[in,out] ptr          pointer to parameter
-    get_file_options_ulllist()
+  @param[in] end              end of the configuration
-    ptr                  [in/out] pointer to parameter
+  @param[in] line             pointer to the line begining
-    end                  [in] end of the configuration
+  @param[in] base             base address for parameter writing (structure
-    line                 [in] pointer to the line begining
-    base                 [in] base address for parameter writing (structure
    like TABLE)
-    parameter            [in] description
+  @param[in] parameter        description
-    mem_root             [in] MEM_ROOT for parameters allocation
+  @param[in] mem_root         MEM_ROOT for parameters allocation
 */
 bool get_file_options_ulllist(char *&ptr, char *end, char *line,
@@ -728,28 +725,28 @@ bool get_file_options_ulllist(char *&ptr, char *end, char *line,
 }
-/*
+/**
-  parse parameters
+  parse parameters.
-  SYNOPSIS
+  @param base                base address for parameter writing (structure like
-    File_parser::parse()
-    base                base address for parameter writing (structure like
                             TABLE)
-    mem_root            MEM_ROOT for parameters allocation
+  @param mem_root            MEM_ROOT for parameters allocation
-    parameters          parameters description
+  @param parameters          parameters description
-    required            number of parameters in the above list. If the file
+  @param required            number of required parameters in above list. If the file
                             contains more parameters than "required", they will
                             be ignored. If the file contains less parameters
                             then "required", non-existing parameters will
                             remain their values.
-    hook                hook called for unknown keys
+  @param hook                hook called for unknown keys
-    hook_data           some data specific for the hook
+  @param hook_data           some data specific for the hook
-  RETURN
+  @retval
-    FALSE - OK
+    FALSE   OK
-    TRUE - error
+  @retval
+    TRUE    error
 */
 my_bool
 File_parser::parse(uchar* base, MEM_ROOT *mem_root,
                   struct File_option *parameters, uint required,
@@ -935,26 +932,25 @@ File_parser::parse(uchar* base, MEM_ROOT *mem_root,
 }
-/*
+/**
-  Dummy unknown key hook
+  Dummy unknown key hook.
-  SYNOPSIS
+  @param[in,out] unknown_key       reference on the line with unknown
-    File_parser_dummy_hook::process_unknown_string()
-    unknown_key          [in/out] reference on the line with unknown
    parameter and the parsing point
-    base                 [in] base address for parameter writing (structure like
+  @param[in] base                  base address for parameter writing
-                              TABLE)
+    (structure like TABLE)
-    mem_root             [in] MEM_ROOT for parameters allocation
+  @param[in] mem_root              MEM_ROOT for parameters allocation
-    end                  [in] the end of the configuration
+  @param[in] end                   the end of the configuration
-  NOTE
+  @note
    This hook used to catch no longer supported keys and process them for
    backward compatibility, but it will not slow down processing of modern
    format files.
    This hook does nothing except debug output.
-  RETURN
+  @retval
    FALSE OK
+  @retval
    TRUE  Error
 */

--- a/sql/procedure.cc
+++ b/sql/procedure.cc
@@ -68,10 +68,13 @@ my_decimal *Item_proc_real::val_decimal(my_decimal *decimal_value)
 }
-/*****************************************************************************
+/**
-** Setup handling of procedure
+  Setup handling of procedure.
-** Return 0 if everything is ok
-*****************************************************************************/
+  @return
+    Return 0 if everything is ok
+*/
 Procedure *
 setup_procedure(THD *thd,ORDER *param,select_result *result,

--- a/sql/protocol.cc
+++ b/sql/protocol.cc
@@ -13,8 +13,10 @@
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
-/*
+/**
-  Low level functions for storing data to be send to the MySQL client
+  @file
+  Low level functions for storing data to be send to the MySQL client.
  The actual communction is handled by the net_xxx functions in net_serv.cc
 */
@@ -53,14 +55,15 @@ bool Protocol_binary::net_store_data(const uchar *from, size_t length)
 }
-/*
+/**
-   Send a error string to client
+  Send a error string to client.
  Design note:
  net_printf_error and net_send_error are low-level functions
  that shall be used only when a new connection is being
  established or at server startup.
  For SIGNAL/RESIGNAL and GET DIAGNOSTICS functionality it's
  critical that every error that can be intercepted is issued in one
  place only, my_message_sql.
@@ -120,16 +123,19 @@ void net_send_error(THD *thd, uint sql_errno, const char *err)
  DBUG_VOID_RETURN;
 }
-/*
+/**
-   Write error package and flush to client
+  Write error package and flush to client.
+  @note
    It's a little too low level, but I don't want to use another buffer for
-   this
+    this.
  Design note:
  net_printf_error and net_send_error are low-level functions
  that shall be used only when a new connection is being
  established or at server startup.
  For SIGNAL/RESIGNAL and GET DIAGNOSTICS functionality it's
  critical that every error that can be intercepted is issued in one
  place only, my_message_sql.
@@ -239,30 +245,27 @@ net_printf_error(THD *thd, uint errcode, ...)
  DBUG_VOID_RETURN;
 }
-/*
+/**
  Return ok to the client.
-  SYNOPSIS
+  The ok packet has the following structure:
-    send_ok()
-    thd			Thread handler
+  - 0               : Marker (1 byte)
-    affected_rows	Number of rows changed by statement
+  - affected_rows	: Stored in 1-9 bytes
-    id			Auto_increment id for first row (if used)
+  - id		: Stored in 1-9 bytes
-    message		Message to send to the client (Used by mysql_status)
+  - server_status	: Copy of thd->server_status;  Can be used by client
+  to check if we are inside an transaction.
-  DESCRIPTION
-    The ok packet has the following structure
-    0			Marker (1 byte)
-    affected_rows	Stored in 1-9 bytes
-    id			Stored in 1-9 bytes
-    server_status	Copy of thd->server_status;  Can be used by client
-			to check if we are inside an transaction
  New in 4.0 protocol
-    warning_count	Stored in 2 bytes; New in 4.1 protocol
+  - warning_count	: Stored in 2 bytes; New in 4.1 protocol
-    message		Stored as packed length (1-9 bytes) + message
+  - message		: Stored as packed length (1-9 bytes) + message.
-			Is not stored if no message
+  Is not stored if no message.
-   If net->no_send_ok return without sending packet
+  If net->no_send_ok return without sending packet.
+  @param thd		   Thread handler
+  @param affected_rows	   Number of rows changed by statement
+  @param id		   Auto_increment id for first row (if used)
+  @param message	   Message to send to the client (Used by mysql_status)
 */
 #ifndef EMBEDDED_LIBRARY
@@ -319,26 +322,23 @@ send_ok(THD *thd, ha_rows affected_rows, ulonglong id, const char *message)
 static uchar eof_buff[1]= { (uchar) 254 };      /* Marker for end of fields */
-/*
+/**
-  Send eof (= end of result set) to the client
+  Send eof (= end of result set) to the client.
-  SYNOPSIS
-    send_eof()
-    thd			Thread handler
-    no_flush		Set to 1 if there will be more data to the client,
-			like in send_fields().
-  DESCRIPTION
+  The eof packet has the following structure:
-    The eof packet has the following structure
-    254			Marker (1 byte)
+  - 254		: Marker (1 byte)
-    warning_count	Stored in 2 bytes; New in 4.1 protocol
+  - warning_count	: Stored in 2 bytes; New in 4.1 protocol
-    status_flag		Stored in 2 bytes;
+  - status_flag	: Stored in 2 bytes;
-			For flags like SERVER_MORE_RESULTS_EXISTS
+  For flags like SERVER_MORE_RESULTS_EXISTS.
  Note that the warning count will not be sent if 'no_flush' is set as
  we don't want to report the warning count until all data is sent to the
  client.
+  @param thd		Thread handler
+  @param no_flush	Set to 1 if there will be more data to the client,
+                    like in send_fields().
 */
 void
@@ -357,7 +357,7 @@ send_eof(THD *thd)
 }
-/*
+/**
  Format EOF packet according to the current protocol and
  write it to the network output buffer.
 */
@@ -388,14 +388,14 @@ static void write_eof_packet(THD *thd, NET *net)
    VOID(my_net_write(net, eof_buff, 1));
 }
-/*
+/**
  Please client to send scrambled_password in old format.
-  SYNOPSYS
-    send_old_password_request()
-    thd thread handle
-  RETURN VALUE
+  @param thd thread handle
+  @retval
    0   ok
+  @retval
    !0  error
 */
@@ -450,14 +450,15 @@ void net_send_error_packet(THD *thd, uint sql_errno, const char *err)
 #endif /* EMBEDDED_LIBRARY */
-/*
+/**
  Faster net_store_length when we know that length is less than 65536.
  We keep a separate version for that range because it's widely used in
  libmysql.
  uint is used as agrument type because of MySQL type conventions:
-  uint for 0..65536
+  - uint for 0..65536
-  ulong for 0..4294967296
+  - ulong for 0..4294967296
-  ulonglong for bigger numbers.
+  - ulonglong for bigger numbers.
 */
 static uchar *net_store_length_fast(uchar *packet, uint length)
@@ -530,27 +531,26 @@ bool Protocol::flush()
 #endif
 }
-/*
+#ifndef EMBEDDED_LIBRARY
-  Send name and type of result to client.
-  SYNOPSIS
+/**
-    send_fields()
+  Send name and type of result to client.
-    THD		Thread data object
-    list	List of items to send to client
-    flag	Bit mask with the following functions:
-		1 send number of rows
-		2 send default values
-                4 don't write eof packet
-  DESCRIPTION
  Sum fields has table name empty and field_name.
-  RETURN VALUES
+  @param THD		Thread data object
+  @param list	        List of items to send to client
+  @param flag	        Bit mask with the following functions:
+                        - 1 send number of rows
+                        - 2 send default values
+                        - 4 don't write eof packet
+  @retval
    0	ok
-    1	Error  (Note that in this case the error is not sent to the client)
+  @retval
+    1	Error  (Note that in this case the error is not sent to the
+    client)
 */
-#ifndef EMBEDDED_LIBRARY
 bool Protocol::send_fields(List<Item> *list, uint flags)
 {
  List_iterator_fast<Item> it(*list);
@@ -704,18 +704,17 @@ bool Protocol::write()
 #endif /* EMBEDDED_LIBRARY */
-/*
+/**
-  Send \0 end terminated string
+  Send \\0 end terminated string.
-  SYNOPSIS
+  @param from	NullS or \\0 terminated string
-    store()
-    from	NullS or \0 terminated string
-  NOTES
+  @note
    In most cases one should use store(from, length) instead of this function
-  RETURN VALUES
+  @retval
    0		ok
+  @retval
    1		error
 */
@@ -728,8 +727,8 @@ bool Protocol::store(const char *from, CHARSET_INFO *cs)
 }
-/*
+/**
-  Send a set of strings as one long string with ',' in between
+  Send a set of strings as one long string with ',' in between.
 */
 bool Protocol::store(I_List<i_string>* str_list)
@@ -781,7 +780,7 @@ bool Protocol_text::store_null()
 #endif
-/*
+/**
  Auxilary function to convert string to the given character set
  and store in network buffer.
 */
@@ -957,13 +956,12 @@ bool Protocol_text::store(Field *field)
 }
-/*
+/**
-   TODO:
+  @todo
  Second_part format ("%06") needs to change when 
  we support 0-6 decimals for time.
 */
 bool Protocol_text::store(MYSQL_TIME *tm)
 {
 #ifndef DBUG_OFF
@@ -1001,8 +999,8 @@ bool Protocol_text::store_date(MYSQL_TIME *tm)
 }
-/*
+/**
-   TODO:
+  @todo 
  Second_part format ("%06") needs to change when 
  we support 0-6 decimals for time.
 */

--- a/sql/records.cc
+++ b/sql/records.cc
@@ -14,7 +14,12 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
-/* Functions for easy reading of records, possible through a cache */
+/**
+  @file
+  @brief
+  Functions for easy reading of records, possible through a cache
+*/
 #include "mysql_priv.h"
@@ -31,25 +36,20 @@ static int rr_index_first(READ_RECORD *info);
 static int rr_index(READ_RECORD *info);
-/*
+/**
-  Initialize READ_RECORD structure to perform full index scan
-  SYNOPSIS 
-    init_read_record_idx()
-      info         READ_RECORD structure to initialize.
-      thd          Thread handle
-      table        Table to be accessed 
-      print_error  If true, call table->file->print_error() if an error
-                   occurs (except for end-of-records error)
-      idx          index to scan
-  DESCRIPTION
  Initialize READ_RECORD structure to perform full index scan (in forward
  direction) using read_record.read_record() interface.
    This function has been added at late stage and is used only by
    UPDATE/DELETE. Other statements perform index scans using
    join_read_first/next functions.
+  @param info         READ_RECORD structure to initialize.
+  @param thd          Thread handle
+  @param table        Table to be accessed
+  @param print_error  If true, call table->file->print_error() if an error
+                      occurs (except for end-of-records error)
+  @param idx          index to scan
 */
 void init_read_record_idx(READ_RECORD *info, THD *thd, TABLE *table,
@@ -284,7 +284,7 @@ static int rr_handle_error(READ_RECORD *info, int error)
 }
-	/* Read a record from head-database */
+/** Read a record from head-database. */
 static int rr_quick(READ_RECORD *info)
 {
@@ -306,20 +306,19 @@ static int rr_quick(READ_RECORD *info)
 }
-/*
+/**
-  Reads first row in an index scan
+  Reads first row in an index scan.
-  SYNOPSIS
+  @param info  	Scan info
-    rr_index_first()
-    info  	Scan info
-  RETURN
+  @retval
    0   Ok
+  @retval
    -1   End of records
+  @retval
    1   Error
 */
 static int rr_index_first(READ_RECORD *info)
 {
  int tmp= info->file->index_first(info->record);
@@ -330,24 +329,22 @@ static int rr_index_first(READ_RECORD *info)
 }
-/*
+/**
-  Reads index sequentially after first row
+  Reads index sequentially after first row.
-  SYNOPSIS
-    rr_index()
-      info  Scan info
-  DESCRIPTION
  Read the next index record (in forward direction) and translate return
  value.
-  RETURN
+  @param info  Scan info
+  @retval
    0   Ok
+  @retval
    -1   End of records
+  @retval
    1   Error
 */
 static int rr_index(READ_RECORD *info)
 {
  int tmp= info->file->index_next(info->record);
@@ -401,22 +398,20 @@ static int rr_from_tempfile(READ_RECORD *info)
 } /* rr_from_tempfile */
-/*
+/**
-  Read a result set record from a temporary file after sorting
+  Read a result set record from a temporary file after sorting.
-  SYNOPSIS
-    rr_unpack_from_tempfile()
-    info                Reference to the context including record descriptors
-  DESCRIPTION
  The function first reads the next sorted record from the temporary file.
  into a buffer. If a success it calls a callback function that unpacks 
  the fields values use in the result set from this buffer into their
  positions in the regular record buffer.
-  RETURN
+  @param info          Reference to the context including record descriptors
-     0 - Record successfully read.
-    -1 - There is no record to be read anymore. 
+  @retval
+    0   Record successfully read.
+  @retval
+    -1   There is no record to be read anymore.
 */
 static int rr_unpack_from_tempfile(READ_RECORD *info)
@@ -454,22 +449,20 @@ static int rr_from_pointers(READ_RECORD *info)
  return tmp;
 }
-/*
+/**
-  Read a result set record from a buffer after sorting
+  Read a result set record from a buffer after sorting.
-  SYNOPSIS
-    rr_unpack_from_buffer()
-    info                   Reference to the context including record descriptors
-  DESCRIPTION
  The function first reads the next sorted record from the sort buffer.
  If a success it calls a callback function that unpacks 
  the fields values use in the result set from this buffer into their
  positions in the regular record buffer.
-  RETURN
+  @param info          Reference to the context including record descriptors
-     0 - Record successfully read.
-    -1 - There is no record to be read anymore. 
+  @retval
+    0   Record successfully read.
+  @retval
+    -1   There is no record to be read anymore.
 */
 static int rr_unpack_from_buffer(READ_RECORD *info)

--- a/sql/repl_failsafe.cc
+++ b/sql/repl_failsafe.cc
@@ -13,6 +13,16 @@
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
+/**
+  @file
+  All of the functions defined in this file which are not used (the ones to
+  handle failsafe) are not used; their code has not been updated for more
+  than one year now so should be considered as BADLY BROKEN. Do not enable
+  it. The used functions (to handle LOAD DATA FROM MASTER, plus some small
+  functions like register_slave()) are working.
+*/
 #include "mysql_priv.h"
 #ifdef HAVE_REPLICATION
@@ -144,11 +154,12 @@ void unregister_slave(THD* thd, bool only_mine, bool need_mutex)
 }
-/*
+/**
-  Register slave in 'slave_list' hash table
+  Register slave in 'slave_list' hash table.
-  RETURN VALUES
+  @return
    0	ok
+  @return
    1	Error.   Error message sent to client
 */
@@ -252,7 +263,8 @@ static int find_target_pos(LEX_MASTER_INFO *mi, IO_CACHE *log, char *errmsg)
  /* Impossible */
 }
-/* 
+/**
+  @details 
  Before 4.0.15 we had a member of THD called log_pos, it was meant for
  failsafe replication code in repl_failsafe.cc which is disabled until
  it is reworked. Event's log_pos used to be preserved through 
@@ -388,8 +400,8 @@ int translate_master(THD* thd, LEX_MASTER_INFO* mi, char* errmsg)
 }
-/*
+/**
-  Caller must delete result when done
+  Caller must delete result when done.
 */
 static Slave_log_event* find_slave_event(IO_CACHE* log,
@@ -428,9 +440,11 @@ static Slave_log_event* find_slave_event(IO_CACHE* log,
  return (Slave_log_event*)ev;
 }
-/*
+/**
-   This function is broken now. See comment for translate_master().
+  This function is broken now. 
- */
+  @seealso translate_master()
+*/
 bool show_new_master(THD* thd)
 {
@@ -466,20 +480,19 @@ bool show_new_master(THD* thd)
  }
 }
-/*
+/**
  Asks the master for the list of its other connected slaves.
  This is for failsafe replication:
  in order for failsafe replication to work, the servers involved in
  replication must know of each other. We accomplish this by having each
  slave report to the master how to reach it, and on connection, each
  slave receives information about where the other slaves are.
-  SYNOPSIS
+  @param mysql           pre-existing connection to the master
-    update_slave_list()
+  @param mi              master info
-    mysql           pre-existing connection to the master
-    mi              master info
-  NOTES
+  @note
    mi is used only to give detailed error messages which include the
    hostname/port of the master, the username used by the slave to connect to
    the master.
@@ -487,10 +500,11 @@ bool show_new_master(THD* thd)
    REPLICATION SLAVE privilege, it will pop in this function because
    SHOW SLAVE HOSTS will fail on the master.
-  RETURN VALUES
+  @retval
    1           error
+  @retval
    0           success
- */
+*/
 int update_slave_list(MYSQL* mysql, Master_info* mi)
 {
@@ -754,11 +768,16 @@ static int fetch_db_tables(THD *thd, MYSQL *mysql, const char *db,
  return 0;
 }
-/*
+/**
  Load all MyISAM tables from master to this slave.
  REQUIREMENTS
-   - No active transaction (flush_relay_log_info would not work in this case)
+    - No active transaction (flush_relay_log_info would not work in this case).
+  @todo
+    - add special option, not enabled
+    by default, to allow inclusion of mysql database into load
+    data from master
 */
 bool load_master_data(THD* thd)

--- a/sql/set_var.cc
+++ b/sql/set_var.cc
@@ -13,9 +13,13 @@
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
-/*
+/**
+  @file
+  @brief
  Handling of MySQL SQL variables
+  @details
  To add a new variable, one has to do the following:
  - Use one of the 'sys_var... classes from set_var.h or write a specific
@@ -28,18 +32,19 @@
  - Don't forget to initialize new fields in global_system_variables and
    max_system_variables!
-  NOTES:
+  @todo
-    - Be careful with var->save_result: sys_var::check() only updates
+    Add full support for the variable character_set (for 4.1)
-    ulonglong_value; so other members of the union are garbage then; to use
-    them you must first assign a value to them (in specific ::check() for
-    example).
-  TODO:
-    - Add full support for the variable character_set (for 4.1)
-    - When updating myisam_delay_key_write, we should do a 'flush tables'
+  @todo
+    When updating myisam_delay_key_write, we should do a 'flush tables'
    of all MyISAM tables to ensure that they are reopen with the
    new attribute.
+  @note
+    Be careful with var->save_result: sys_var::check() only updates
+    ulonglong_value; so other members of the union are garbage then; to use
+    them you must first assign a value to them (in specific ::check() for
+    example).
 */
 #ifdef USE_PRAGMA_IMPLEMENTATION
@@ -819,9 +824,9 @@ static void sys_default_ftb_syntax(THD *thd, enum_var_type type)
 }
-/*
+/**
  If one sets the LOW_PRIORIY UPDATES flag, we also must change the
-  used lock type
+  used lock type.
 */
 static void fix_low_priority_updates(THD *thd, enum_var_type type)
@@ -843,8 +848,8 @@ fix_myisam_max_sort_file_size(THD *thd, enum_var_type type)
    (my_off_t) global_system_variables.myisam_max_sort_file_size;
 }
-/*
+/**
-  Set the OPTION_BIG_SELECTS flag if max_join_size == HA_POS_ERROR
+  Set the OPTION_BIG_SELECTS flag if max_join_size == HA_POS_ERROR.
 */
 static void fix_max_join_size(THD *thd, enum_var_type type)
@@ -859,7 +864,7 @@ static void fix_max_join_size(THD *thd, enum_var_type type)
 }
-/*
+/**
  Can't change the 'next' tx_isolation while we are already in
  a transaction
 */
@@ -875,7 +880,7 @@ static int check_tx_isolation(THD *thd, set_var *var)
 /*
  If one doesn't use the SESSION modifier, the isolation level
-  is only active for the next command
+  is only active for the next command.
 */
 static void fix_tx_isolation(THD *thd, enum_var_type type)
 {
@@ -1447,9 +1452,12 @@ bool sys_var::check_set(THD *thd, set_var *var, TYPELIB *enum_names)
 }
-/*
+/**
-  Return an Item for a variable.  Used with @@[global.]variable_name
+  Return an Item for a variable.
-  If type is not given, return local value if exists, else global
+  Used with @@[global.]variable_name.
+  If type is not given, return local value if exists, else global.
 */
 Item *sys_var::item(THD *thd, enum_var_type var_type, LEX_STRING *base)
@@ -1611,7 +1619,7 @@ uchar *sys_var_thd_bit::value_ptr(THD *thd, enum_var_type type,
 }
-/* Update a date_time format variable based on given value */
+/** Update a date_time format variable based on given value. */
 void sys_var_thd_date_time_format::update2(THD *thd, enum_var_type type,
 					   DATE_TIME_FORMAT *new_value)
@@ -2028,6 +2036,12 @@ bool sys_var_key_buffer_size::update(THD *thd, set_var *var)
 }
+/**
+  @todo
+  Abort if some other thread is changing the key cache.
+  This should be changed so that we wait until the previous
+  assignment is done and then do the new assign
+*/
 bool sys_var_key_cache_long::update(THD *thd, set_var *var)
 {
  ulong tmp= (ulong) var->value->val_int();
@@ -2720,23 +2734,20 @@ static uchar *get_error_count(THD *thd)
 }
-/*
+/**
-  Get the tmpdir that was specified or chosen by default
+  Get the tmpdir that was specified or chosen by default.
-  SYNOPSIS
-    get_tmpdir()
-    thd		thread handle
-  DESCRIPTION
  This is necessary because if the user does not specify a temporary
  directory via the command line, one is chosen based on the environment
  or system defaults.  But we can't just always use mysql_tmpdir, because
  that is actually a call to my_tmpdir() which cycles among possible
  temporary directories.
-  RETURN VALUES
+  @param thd		thread handle
+  @retval
    ptr		pointer to NUL-terminated string
- */
+*/
 static uchar *get_tmpdir(THD *thd)
 {
  if (opt_mysql_tmpdir)
@@ -2751,16 +2762,16 @@ static uchar *get_tmpdir(THD *thd)
  - Update loop
 ****************************************************************************/
-/*
+/**
-  Find variable name in option my_getopt structure used for command line args
+  Find variable name in option my_getopt structure used for
+  command line args.
-  SYNOPSIS
+  @param opt	option structure array to search in
-    find_option()
+  @param name	variable name
-    opt		option structure array to search in
-    name	variable name
-  RETURN VALUES
+  @retval
    0		Error
+  @retval
    ptr		pointer to option structure
 */
@@ -2783,8 +2794,8 @@ static struct my_option *find_option(struct my_option *opt, const char *name)
 }
-/*
+/**
-  Return variable name and length for hashing of variables
+  Return variable name and length for hashing of variables.
 */
 static uchar *get_sys_var_length(const sys_var *var, size_t *length,
@@ -2986,17 +2997,17 @@ int mysql_append_static_vars(const SHOW_VAR *show_vars, uint count)
 }
-/*
+/**
-  Find a user set-table variable
+  Find a user set-table variable.
-  SYNOPSIS
+  @param str	   Name of system variable to find
-    intern_find_sys_var()
+  @param length    Length of variable.  zero means that we should use strlen()
-    str		Name of system variable to find
-    length	Length of variable.  zero means that we should use strlen()
                   on the variable
+  @param no_error  Refuse to emit an error, even if one occurred.
-  RETURN VALUES
+  @retval
    pointer	pointer to variable definitions
+  @retval
    0		Unknown variable (error message is given)
 */
@@ -3017,25 +3028,23 @@ sys_var *intern_find_sys_var(const char *str, uint length, bool no_error)
 }
-/*
+/**
-  Execute update of all variables
+  Execute update of all variables.
-  SYNOPSIS
-  sql_set
-    THD		Thread id
-    set_var	List of variables to update
-  DESCRIPTION
  First run a check of all variables that all updates will go ok.
  If yes, then execute all updates, returning an error if any one failed.
  This should ensure that in all normal cases none all or variables are
-    updated
+  updated.
-    RETURN VALUE
+  @param THD		Thread id
+  @param var_list       List of variables to update
+  @retval
    0	ok
+  @retval
    1	ERROR, message sent (normally no variables was updated)
+  @retval
    -1  ERROR, message not sent
 */
@@ -3064,20 +3073,19 @@ int sql_set_variables(THD *thd, List<set_var_base> *var_list)
 }
-/*
+/**
-  Say if all variables set by a SET support the ONE_SHOT keyword (currently,
+  Say if all variables set by a SET support the ONE_SHOT keyword
-  only character set and collation do; later timezones will).
+  (currently, only character set and collation do; later timezones
+  will).
-  SYNOPSIS
-  not_all_support_one_shot
+  @param var_list	List of variables to update
-    set_var	List of variables to update
-  NOTES
+  @note
    It has a "not_" because it makes faster tests (no need to "!")
-    RETURN VALUE
+  @retval
    0	all variables of the list support ONE_SHOT
+  @retval
    1	at least one does not support ONE_SHOT
 */
@@ -3136,16 +3144,16 @@ int set_var::check(THD *thd)
 }
-/*
+/**
-  Check variable, but without assigning value (used by PS)
+  Check variable, but without assigning value (used by PS).
-  SYNOPSIS
+  @param thd		thread handler
-    set_var::light_check()
-    thd		thread handler
-  RETURN VALUE
+  @retval
    0	ok
+  @retval
    1	ERROR, message sent (normally no variables was updated)
+  @retval
    -1   ERROR, message not sent
 */
 int set_var::light_check(THD *thd)
@@ -3193,16 +3201,16 @@ int set_var_user::check(THD *thd)
 }
-/*
+/**
-  Check variable, but without assigning value (used by PS)
+  Check variable, but without assigning value (used by PS).
-  SYNOPSIS
+  @param thd		thread handler
-    set_var_user::light_check()
-    thd		thread handler
-  RETURN VALUE
+  @retval
    0	ok
+  @retval
    1	ERROR, message sent (normally no variables was updated)
+  @retval
    -1   ERROR, message not sent
 */
 int set_var_user::light_check(THD *thd)
@@ -3377,13 +3385,15 @@ bool sys_var_thd_table_type::update(THD *thd, set_var *var)
 Functions to handle sql_mode
 ****************************************************************************/
-/*
+/**
-  Make string representation of mode
+  Make string representation of mode.
-  SYNOPSIS
+  @param[in]  thd    thread handler
-    thd   in  thread handler
+  @param[in]  val    sql_mode value
-    val   in  sql_mode value
+  @param[out] len    pointer on length of string
-    rep   out pointer pointer to string with sql_mode representation
+  @return
+    pointer to string with sql_mode representation
 */
 bool
@@ -3454,7 +3464,7 @@ void fix_sql_mode_var(THD *thd, enum_var_type type)
  }
 }
-/* Map database specific bits to function bits */
+/** Map database specific bits to function bits. */
 ulong fix_sql_mode(ulong sql_mode)
 {

--- a/sql/sp.cc
+++ b/sql/sp.cc
@@ -249,19 +249,18 @@ Stored_routine_creation_ctx::load_from_db(THD *thd,
 /*************************************************************************/
-/*
+/**
  Open the mysql.proc table for read.
-  SYNOPSIS
+  @param thd     Thread context
-    open_proc_table_for_read()
+  @param backup  Pointer to Open_tables_state instance where information about
-      thd     Thread context
-      backup  Pointer to Open_tables_state instance where information about
                 currently open tables will be saved, and from which will be
                 restored when we will end work with mysql.proc.
-  RETURN
+  @retval
    0	Error
-    #	Pointer to TABLE object of mysql.proc
+  @retval
+    \#	Pointer to TABLE object of mysql.proc
 */
 TABLE *open_proc_table_for_read(THD *thd, Open_tables_state *backup)
@@ -281,19 +280,18 @@ TABLE *open_proc_table_for_read(THD *thd, Open_tables_state *backup)
 }
-/*
+/**
  Open the mysql.proc table for update.
-  SYNOPSIS
+  @param thd  Thread context
-    open_proc_table_for_update()
-      thd  Thread context
-  NOTES
+  @note
    Table opened with this call should closed using close_thread_tables().
-  RETURN
+  @retval
    0	Error
-    #	Pointer to TABLE object of mysql.proc
+  @retval
+    \#	Pointer to TABLE object of mysql.proc
 */
 static TABLE *open_proc_table_for_update(THD *thd)
@@ -310,19 +308,18 @@ static TABLE *open_proc_table_for_update(THD *thd)
 }
-/*
+/**
  Find row in open mysql.proc table representing stored routine.
-  SYNOPSIS
+  @param thd    Thread context
-    db_find_routine_aux()
+  @param type   Type of routine to find (function or procedure)
-      thd    Thread context
+  @param name   Name of routine
-      type   Type of routine to find (function or procedure)
+  @param table  TABLE object for open mysql.proc table.
-      name   Name of routine
-      table  TABLE object for open mysql.proc table.
-  RETURN VALUE
+  @retval
-    SP_OK           - Routine found
+    SP_OK             Routine found
-    SP_KEY_NOT_FOUND- No routine with given name
+  @retval
+    SP_KEY_NOT_FOUND  No routine with given name
 */
 static int
@@ -357,25 +354,24 @@ db_find_routine_aux(THD *thd, int type, sp_name *name, TABLE *table)
 }
-/*
+/**
  Find routine definition in mysql.proc table and create corresponding
  sp_head object for it.
-  SYNOPSIS
+  @param thd   Thread context
-    db_find_routine()
+  @param type  Type of routine (TYPE_ENUM_PROCEDURE/...)
-      thd   Thread context
+  @param name  Name of routine
-      type  Type of routine (TYPE_ENUM_PROCEDURE/...)
+  @param sphp  Out parameter in which pointer to created sp_head
-      name  Name of routine
-      sphp  Out parameter in which pointer to created sp_head
               object is returned (0 in case of error).
-  NOTE
+  @note
    This function may damage current LEX during execution, so it is good
    idea to create temporary LEX and make it active before calling it.
-  RETURN VALUE
+  @retval
-    0     - Success
+    0       Success
-    non-0 - Error (may be one of special codes like SP_KEY_NOT_FOUND)
+  @retval
+    non-0   Error (may be one of special codes like SP_KEY_NOT_FOUND)
 */
 static int
@@ -1284,22 +1280,21 @@ sp_show_create_routine(THD *thd, int type, sp_name *name)
 }
-/*
+/**
  Obtain object representing stored procedure/function by its name from
  stored procedures cache and looking into mysql.proc if needed.
-  SYNOPSIS
+  @param thd          thread context
-    sp_find_routine()
+  @param type         type of object (TYPE_ENUM_FUNCTION or TYPE_ENUM_PROCEDURE)
-      thd        - thread context
+  @param name         name of procedure
-      type       - type of object (TYPE_ENUM_FUNCTION or TYPE_ENUM_PROCEDURE)
+  @param cp           hash to look routine in
-      name       - name of procedure
+  @param cache_only   if true perform cache-only lookup
-      cp         - hash to look routine in
-      cache_only - if true perform cache-only lookup
                      (Don't look in mysql.proc).
-  RETURN VALUE
+  @retval
-    Non-0 pointer to sp_head object for the procedure, or
+    NonNULL pointer to sp_head object for the procedure
-    0 - in case of error.
+  @retval
+    NULL    in case of error.
 */
 sp_head *
@@ -1395,7 +1390,7 @@ sp_find_routine(THD *thd, int type, sp_name *name, sp_cache **cp,
 }
-/*
+/**
  This is used by sql_acl.cc:mysql_routine_grant() and is used to find
  the routines in 'routines'.
 */
@@ -1444,18 +1439,17 @@ sp_exist_routines(THD *thd, TABLE_LIST *routines, bool any, bool no_error)
 }
-/*
+/**
  Check if a routine exists in the mysql.proc table, without actually
-  parsing the definition. (Used for dropping)
+  parsing the definition. (Used for dropping).
-  SYNOPSIS
+  @param thd          thread context
-    sp_routine_exists_in_table()
+  @param name         name of procedure
-      thd        - thread context
-      name       - name of procedure
-  RETURN VALUE
+  @retval
-    0     - Success
+    0       Success
-    non-0 - Error;  SP_OPEN_TABLE_FAILED or SP_KEY_NOT_FOUND
+  @retval
+    non-0   Error;  SP_OPEN_TABLE_FAILED or SP_KEY_NOT_FOUND
 */
 int
@@ -1477,7 +1471,7 @@ sp_routine_exists_in_table(THD *thd, int type, sp_name *name)
 }
-/*
+/**
  Structure that represents element in the set of stored routines
  used by statement or routine.
 */
@@ -1485,14 +1479,16 @@ struct Sroutine_hash_entry;
 struct Sroutine_hash_entry
 {
-  /* Set key consisting of one-byte routine type and quoted routine name. */
+  /**
+    Set key consisting of one-byte routine type and quoted routine name.
+  */
  LEX_STRING key;
-  /*
+  /**
    Next element in list linking all routines in set. See also comments
    for LEX::sroutine/sroutine_list and sp_head::m_sroutines.
  */
  Sroutine_hash_entry *next;
-  /*
+  /**
    Uppermost view which directly or indirectly uses this routine.
    0 if routine is not used in view. Note that it also can be 0 if
    statement uses routine both via view and directly.
@@ -1510,24 +1506,22 @@ extern "C" uchar* sp_sroutine_key(const uchar *ptr, size_t *plen,
 }
-/*
+/**
  Check if
   - current statement (the one in thd->lex) needs table prelocking
   - first routine in thd->lex->sroutines_list needs to execute its body in
     prelocked mode.
-  SYNOPSIS
+  @param thd                  Current thread, thd->lex is the statement to be
-    sp_get_prelocking_info()
-      thd                  Current thread, thd->lex is the statement to be
                              checked.
-      need_prelocking      OUT TRUE  - prelocked mode should be activated
+  @param[out] need_prelocking    TRUE  - prelocked mode should be activated
-                                       before executing the statement
+                                 before executing the statement; 
                                 FALSE - Don't activate prelocking
-      first_no_prelocking  OUT TRUE  - Tables used by first routine in
+  @param[out] first_no_prelocking  TRUE  - Tables used by first routine in
                                   thd->lex->sroutines_list should be
-                                       prelocked.
+                                   prelocked. FALSE - Otherwise.
-                               FALSE - Otherwise.
-  NOTES 
+  @note
    This function assumes that for any "CALL proc(...)" statement routines_list 
    will have 'proc' as first element (it may have several, consider e.g.
    "proc(sp_func(...)))". This property is currently guaranted by the parser.
@@ -1547,36 +1541,37 @@ void sp_get_prelocking_info(THD *thd, bool *need_prelocking,
 }
-/*
+/**
  Auxilary function that adds new element to the set of stored routines
  used by statement.
-  SYNOPSIS
-    add_used_routine()
-      lex             LEX representing statement
-      arena           Arena in which memory for new element will be allocated
-      key             Key for the hash representing set
-      belong_to_view  Uppermost view which uses this routine
-                      (0 if routine is not used by view)
-  NOTES
-    Will also add element to end of 'LEX::sroutines_list' list.
  In case when statement uses stored routines but does not need
  prelocking (i.e. it does not use any tables) we will access the
  elements of LEX::sroutines set on prepared statement re-execution.
  Because of this we have to allocate memory for both hash element
  and copy of its key in persistent arena.
-  TODO
+  @param lex             LEX representing statement
+  @param arena           Arena in which memory for new element will be
+                         allocated
+  @param key             Key for the hash representing set
+  @param belong_to_view  Uppermost view which uses this routine
+                         (0 if routine is not used by view)
+  @note
+    Will also add element to end of 'LEX::sroutines_list' list.
+  @todo
    When we will got rid of these accesses on re-executions we will be
    able to allocate memory for hash elements in non-persitent arena
    and directly use key values from sp_head::m_sroutines sets instead
    of making their copies.
-  RETURN VALUE
+  @retval
-    TRUE  - new element was added.
+    TRUE   new element was added.
-    FALSE - element was not added (because it is already present in the set).
+  @retval
+    FALSE  element was not added (because it is already present in
+    the set).
 */
 static bool add_used_routine(LEX *lex, Query_arena *arena,
@@ -1606,24 +1601,22 @@ static bool add_used_routine(LEX *lex, Query_arena *arena,
 }
-/*
+/**
  Add routine which is explicitly used by statement to the set of stored
  routines used by this statement.
-  SYNOPSIS
+  To be friendly towards prepared statements one should pass
-    sp_add_used_routine()
+  persistent arena as second argument.
-      lex     - LEX representing statement
-      arena   - arena in which memory for new element of the set
+  @param lex       LEX representing statement
+  @param arena     arena in which memory for new element of the set
                   will be allocated
-      rt      - routine name
+  @param rt        routine name
-      rt_type - routine type (one of TYPE_ENUM_PROCEDURE/...)
+  @param rt_type   routine type (one of TYPE_ENUM_PROCEDURE/...)
-  NOTES
+  @note
    Will also add element to end of 'LEX::sroutines_list' list (and will
    take into account that this is explicitly used routine).
-    To be friendly towards prepared statements one should pass
-    persistent arena as second argument.
 */
 void sp_add_used_routine(LEX *lex, Query_arena *arena,
@@ -1636,13 +1629,11 @@ void sp_add_used_routine(LEX *lex, Query_arena *arena,
 }
-/*
+/**
  Remove routines which are only indirectly used by statement from
  the set of routines used by this statement.
-  SYNOPSIS
+  @param lex  LEX representing statement
-    sp_remove_not_own_routines()
-      lex  LEX representing statement
 */
 void sp_remove_not_own_routines(LEX *lex)
@@ -1665,16 +1656,14 @@ void sp_remove_not_own_routines(LEX *lex)
 }
-/*
+/**
  Merge contents of two hashes representing sets of routines used
  by statements or by other routines.
-  SYNOPSIS
+  @param dst   hash to which elements should be added
-    sp_update_sp_used_routines()
+  @param src   hash from which elements merged
-      dst - hash to which elements should be added
-      src - hash from which elements merged
-  NOTE
+  @note
    This procedure won't create new Sroutine_hash_entry objects,
    instead it will simply add elements from source to destination
    hash. Thus time of life of elements in destination hash becomes
@@ -1694,18 +1683,17 @@ void sp_update_sp_used_routines(HASH *dst, HASH *src)
 }
-/*
+/**
  Add contents of hash representing set of routines to the set of
  routines used by statement.
-  SYNOPSIS
+  @param thd             Thread context
-    sp_update_stmt_used_routines()
+  @param lex             LEX representing statement
-      thd             Thread context
+  @param src             Hash representing set from which routines will
-      lex             LEX representing statement
+                         be added
-      src             Hash representing set from which routines will be added
+  @param belong_to_view  Uppermost view which uses these routines, 0 if none
-      belong_to_view  Uppermost view which uses these routines, 0 if none
-  NOTE
+  @note
    It will also add elements to end of 'LEX::sroutines_list' list.
 */
@@ -1721,18 +1709,17 @@ sp_update_stmt_used_routines(THD *thd, LEX *lex, HASH *src,
 }
-/*
+/**
  Add contents of list representing set of routines to the set of
  routines used by statement.
-  SYNOPSIS
+  @param thd             Thread context
-    sp_update_stmt_used_routines()
+  @param lex             LEX representing statement
-      thd             Thread context
+  @param src             List representing set from which routines will
-      lex             LEX representing statement
+                         be added
-      src             List representing set from which routines will be added
+  @param belong_to_view  Uppermost view which uses these routines, 0 if none
-      belong_to_view  Uppermost view which uses these routines, 0 if none
-  NOTE
+  @note
    It will also add elements to end of 'LEX::sroutines_list' list.
 */
@@ -1745,27 +1732,28 @@ static void sp_update_stmt_used_routines(THD *thd, LEX *lex, SQL_LIST *src,
 }
-/*
+/**
  Cache sub-set of routines used by statement, add tables used by these
  routines to statement table list. Do the same for all routines used
  by these routines.
-  SYNOPSIS
+  @param thd               thread context
-    sp_cache_routines_and_add_tables_aux()
+  @param lex               LEX representing statement
-      thd              - thread context
+  @param start             first routine from the list of routines to be cached
-      lex              - LEX representing statement
-      start            - first routine from the list of routines to be cached
                           (this list defines mentioned sub-set).
-      first_no_prelock - If true, don't add tables or cache routines used by
+  @param first_no_prelock  If true, don't add tables or cache routines used by
                           the body of the first routine (i.e. *start)
                           will be executed in non-prelocked mode.
-  NOTE
+  @param tabs_changed      Set to TRUE some tables were added, FALSE otherwise
+  @note
    If some function is missing this won't be reported here.
    Instead this fact will be discovered during query execution.
-  RETURN VALUE
+  @retval
-     0     - success
+    0       success
-     non-0 - failure
+  @retval
+    non-0   failure
 */
 static int
@@ -1857,21 +1845,20 @@ sp_cache_routines_and_add_tables_aux(THD *thd, LEX *lex,
 }
-/*
+/**
  Cache all routines from the set of used by statement, add tables used
  by those routines to statement table list. Do the same for all routines
  used by those routines.
-  SYNOPSIS
+  @param thd               thread context
-    sp_cache_routines_and_add_tables()
+  @param lex               LEX representing statement
-      thd              - thread context
+  @param first_no_prelock  If true, don't add tables or cache routines used by
-      lex              - LEX representing statement
-      first_no_prelock - If true, don't add tables or cache routines used by
                           the body of the first routine (i.e. *start)
-  RETURN VALUE
+  @retval
-     0     - success
+    0       success
-     non-0 - failure
+  @retval
+    non-0   failure
 */
 int
@@ -1883,20 +1870,21 @@ sp_cache_routines_and_add_tables(THD *thd, LEX *lex, bool first_no_prelock)
 }
-/*
+/**
-  Add all routines used by view to the set of routines used by statement.
+  Add all routines used by view to the set of routines used by
+  statement.
  Add tables used by those routines to statement table list. Do the same
  for all routines used by these routines.
-  SYNOPSIS
+  @param thd   Thread context
-    sp_cache_routines_and_add_tables_for_view()
+  @param lex   LEX representing statement
-      thd   Thread context
+  @param view  Table list element representing view
-      lex   LEX representing statement
-      view  Table list element representing view
-  RETURN VALUE
+  @retval
-     0     - success
+    0       success
-     non-0 - failure
+  @retval
+    non-0   failure
 */
 int
@@ -1911,20 +1899,19 @@ sp_cache_routines_and_add_tables_for_view(THD *thd, LEX *lex, TABLE_LIST *view)
 }
-/*
+/**
  Add triggers for table to the set of routines used by statement.
  Add tables used by them to statement table list. Do the same for
  all implicitly used routines.
-  SYNOPSIS
+  @param thd    thread context
-    sp_cache_routines_and_add_tables_for_triggers()
+  @param lex    LEX respresenting statement
-      thd    thread context
+  @param table  Table list element for table with trigger
-      lex    LEX respresenting statement
-      table  Table list element for table with trigger
-  RETURN VALUE
+  @retval
-     0     - success
+    0       success
-     non-0 - failure
+  @retval
+    non-0   failure
 */
 int
@@ -1970,10 +1957,12 @@ sp_cache_routines_and_add_tables_for_triggers(THD *thd, LEX *lex,
 }
-/*
+/**
- * Generates the CREATE... string from the table information.
+  Generates the CREATE... string from the table information.
- * Returns TRUE on success, FALSE on (alloc) failure.
- */
+  @return
+    Returns TRUE on success, FALSE on (alloc) failure.
+*/
 static bool
 create_string(THD *thd, String *buf,
 	      int type,

--- a/sql/sp_head.cc
+++ b/sql/sp_head.cc
@@ -80,19 +80,20 @@ sp_map_item_type(enum enum_field_types type)
 }
-/*
+/**
  Return a string representation of the Item value.
-  NOTE: If the item has a string result type, the string is escaped
+  @param thd     thread handle
-  according to its character set.
+  @param str     string buffer for representation of the value
-  SYNOPSIS
+  @note
-    item    a pointer to the Item
+    If the item has a string result type, the string is escaped
-    str     string buffer for representation of the value
+    according to its character set.
-  RETURN
+  @retval
    NULL      on error
-    a pointer to valid a valid string on success
+  @retval
+    non-NULL  a pointer to valid a valid string on success
 */
 static String *
@@ -137,15 +138,11 @@ sp_get_item_value(THD *thd, Item *item, String *str)
 }
-/*
+/**
-  SYNOPSIS
-    sp_get_flags_for_command()
-  DESCRIPTION
   Returns a combination of:
-    * sp_head::MULTI_RESULTS: added if the 'cmd' is a command that might
+   - sp_head::MULTI_RESULTS: added if the 'cmd' is a command that might
     result in multiple result sets being sent back.
-    * sp_head::CONTAINS_DYNAMIC_SQL: added if 'cmd' is one of PREPARE,
+   - sp_head::CONTAINS_DYNAMIC_SQL: added if 'cmd' is one of PREPARE,
     EXECUTE, DEALLOCATE.
 */
@@ -286,17 +283,16 @@ sp_get_flags_for_command(LEX *lex)
  return flags;
 }
-/*
+/**
  Prepare an Item for evaluation (call of fix_fields).
-  SYNOPSIS
+  @param thd       thread handler
-    sp_prepare_func_item()
+  @param it_addr   pointer on item refernce
-    thd       thread handler
-    it_addr   pointer on item refernce
-  RETURN
+  @retval
    NULL      error
-    prepared item
+  @retval
+    non-NULL  prepared item
 */
 Item *
@@ -316,17 +312,16 @@ sp_prepare_func_item(THD* thd, Item **it_addr)
 }
-/*
+/**
  Evaluate an expression and store the result in the field.
-  SYNOPSIS
+  @param thd                    current thread object
-    sp_eval_expr()
+  @param result_field           the field to store the result
-      thd                   - current thread object
+  @param expr_item_ptr          the root item of the expression
-      expr_item             - the root item of the expression
-      result_field          - the field to store the result
-  RETURN VALUES
+  @retval
    FALSE  on success
+  @retval
    TRUE   on error
 */
@@ -386,6 +381,9 @@ sp_eval_expr(THD *thd, Field *result_field, Item **expr_item_ptr)
 *
 */
+/**
+  Init the qualified name from the db and name.
+*/
 void
 sp_name::init_qname(THD *thd)
 {
@@ -400,16 +398,17 @@ sp_name::init_qname(THD *thd)
 }
-/*
+/**
  Check that the name 'ident' is ok.  It's assumed to be an 'ident'
  from the parser, so we only have to check length and trailing spaces.
  The former is a standard requirement (and 'show status' assumes a
  non-empty name), the latter is a mysql:ism as trailing spaces are
  removed by get_field().
-  RETURN
+  @retval
-   TRUE  - bad name
+    TRUE    bad name
-   FALSE - name is ok
+  @retval
+    FALSE   name is ok
 */
 bool
@@ -742,7 +741,7 @@ sp_head::destroy()
 }
-/*
+/**
  This is only used for result fields from functions (both during
  fix_length_and_dec() and evaluation).
 */
@@ -861,29 +860,23 @@ int cmp_splocal_locations(Item_splocal * const *a, Item_splocal * const *b)
 */
-/*
+/**
-  Replace thd->query{_length} with a string that one can write to the binlog
+  Replace thd->query{_length} with a string that one can write to
-  or the query cache.
+  the binlog.
-  SYNOPSIS
-    subst_spvars()
-      thd        Current thread. 
-      instr      Instruction (we look for Item_splocal instances in
-                 instr->free_list)
-      query_str  Original query string
-  DESCRIPTION
  The binlog-suitable string is produced by replacing references to SP local 
-  variables with NAME_CONST('sp_var_name', value) calls. To make this string
+  variables with NAME_CONST('sp_var_name', value) calls.
-  suitable for the query cache this function allocates some additional space
-  for the query cache flags.
-  RETURN
+  @param thd        Current thread.
-    FALSE  on success
+  @param instr      Instruction (we look for Item_splocal instances in
+                    instr->free_list)
+  @param query_str  Original query string
+  @return
+    - FALSE  on success.
    thd->query{_length} either has been appropriately replaced or there
    is no need for replacements.
-    TRUE   out of memory error.
+    - TRUE   out of memory error.
 */
 static bool
@@ -1002,14 +995,17 @@ void sp_head::recursion_level_error(THD *thd)
 }
-/*
+/**
-  Execute the routine. The main instruction jump loop is there 
+  Execute the routine. The main instruction jump loop is there.
  Assume the parameters already set.
+  @todo
+    - Will write this SP statement into binlog separately 
+    (TODO: consider changing the condition to "not inside event union")
-  RETURN
+  @retval
    FALSE  on success
+  @retval
    TRUE   on error
 */
 bool
@@ -1299,21 +1295,25 @@ sp_head::execute(THD *thd)
 #ifndef NO_EMBEDDED_ACCESS_CHECKS
-/*
+/**
  set_routine_security_ctx() changes routine security context, and
  checks if there is an EXECUTE privilege in new context.  If there is
  no EXECUTE privilege, it changes the context back and returns a
  error.
-  SYNOPSIS
+  @param thd         thread handle
-    set_routine_security_ctx()
+  @param sp          stored routine to change the context for
-      thd         thread handle
+  @param is_proc     TRUE is procedure, FALSE if function
-      sp          stored routine to change the context for
+  @param save_ctx    pointer to an old security context
-      is_proc     TRUE is procedure, FALSE if function
-      save_ctx    pointer to an old security context
-  RETURN
+  @todo
+    - Cache if the definer has the right to use the object on the
+    first usage and only reset the cache if someone does a GRANT
+    statement that 'may' affect this.
+  @retval
    TRUE   if there was a error, and the context wasn't changed.
+  @retval
    FALSE  if the context was changed.
 */
@@ -1356,22 +1356,27 @@ set_routine_security_ctx(THD *thd, sp_head *sp, bool is_proc,
 /**
  Execute trigger stored program.
-  Execute a trigger:
+  - changes security context for triggers
-   - changes security context for triggers;
+  - switch to new memroot
-   - switch to new memroot;
+  - call sp_head::execute
-   - call sp_head::execute;
+  - restore old memroot
-   - restore old memroot;
+  - restores security context
-   - restores security context.
-  @param thd        Thread context.
+  @param thd               Thread handle
-  @param db_name    Database name.
+  @param db                database name
-  @param table_name Table name.
+  @param table             table name
-  @param grant_info GRANT_INFO structure to be filled with information
+  @param grant_info        GRANT_INFO structure to be filled with
-                    about definer's privileges on subject table.
+                           information about definer's privileges
+                           on subject table
-  @return Error status.
+  @todo
-    @retval FALSE on success.
+    - TODO: we should create sp_rcontext once per command and reuse it
-    @retval TRUE  on error.
+    on subsequent executions of a trigger.
+  @retval
+    FALSE  on success
+  @retval
+    TRUE   on error
 */
 bool
@@ -1479,8 +1484,9 @@ sp_head::execute_trigger(THD *thd,
 }
-/*
+/**
-  Execute a function:
+  Execute a function.
   - evaluate parameters
   - changes security context for SUID routines
   - switch to new memroot
@@ -1489,17 +1495,25 @@ sp_head::execute_trigger(THD *thd,
   - evaluate the return value
   - restores security context
-  SYNOPSIS
+  @param thd               Thread handle
-    sp_head::execute_function()
+  @param argp              Passed arguments (these are items from containing
-      thd               Thread handle
-      argp              Passed arguments (these are items from containing
                           statement?)
-      argcount          Number of passed arguments. We need to check if this is
+  @param argcount          Number of passed arguments. We need to check if
-                        correct.
+                           this is correct.
-      return_value_fld  Save result here.
+  @param return_value_fld  Save result here.
+  @todo
+    We should create sp_rcontext once per command and reuse
+    it on subsequent executions of a function/trigger.
-  RETURN
+  @todo
+    In future we should associate call arena/mem_root with
+    sp_rcontext and allocate all these objects (and sp_rcontext
+    itself) on it directly rather than juggle with arenas.
+  @retval
    FALSE  on success
+  @retval
    TRUE   on error
 */
@@ -1716,14 +1730,8 @@ sp_head::execute_function(THD *thd, Item **argp, uint argcount,
 }
-/*
+/**
  Execute a procedure. 
-  SYNOPSIS
-    sp_head::execute_procedure()
-      thd    Thread handle
-      args   List of values passed as arguments.
-  DESCRIPTION
  The function does the following steps:
   - Set all parameters 
@@ -1732,8 +1740,12 @@ sp_head::execute_function(THD *thd, Item **argp, uint argcount,
   - copy back values of INOUT and OUT parameters
   - restores security context
-  RETURN
+  @param thd    Thread handle
+  @param args   List of values passed as arguments.
+  @retval
    FALSE  on success
+  @retval
    TRUE   on error
 */
@@ -1935,7 +1947,7 @@ sp_head::execute_procedure(THD *thd, List<Item> *args)
 }
-// Reset lex during parsing, before we parse a sub statement.
+/// Reset lex during parsing, before we parse a sub statement.
 void
 sp_head::reset_lex(THD *thd)
 {
@@ -1968,7 +1980,7 @@ sp_head::reset_lex(THD *thd)
  DBUG_VOID_RETURN;
 }
-// Restore lex during parsing, after we have parsed a sub statement.
+/// Restore lex during parsing, after we have parsed a sub statement.
 void
 sp_head::restore_lex(THD *thd)
 {
@@ -2011,6 +2023,9 @@ sp_head::restore_lex(THD *thd)
  DBUG_VOID_RETURN;
 }
+/**
+  Put the instruction on the backpatch list, associated with the label.
+*/
 void
 sp_head::push_backpatch(sp_instr *i, sp_label_t *lab)
 {
@@ -2024,6 +2039,10 @@ sp_head::push_backpatch(sp_instr *i, sp_label_t *lab)
  }
 }
+/**
+  Update all instruction with this label in the backpatch list to
+  the current position.
+*/
 void
 sp_head::backpatch(sp_label_t *lab)
 {
@@ -2038,19 +2057,18 @@ sp_head::backpatch(sp_label_t *lab)
  }
 }
-/*
+/**
  Prepare an instance of Create_field for field creation (fill all necessary
  attributes).
-  SYNOPSIS
+  @param[in]  thd          Thread handle
-    sp_head::fill_field_definition()
+  @param[in]  lex          Yacc parsing context
-      thd         [IN] Thread handle
+  @param[in]  field_type   Field type
-      lex         [IN] Yacc parsing context
+  @param[out] field_def    An instance of create_field to be filled
-      field_type  [IN] Field type
-      field_def   [OUT] An instance of Create_field to be filled
-  RETURN
+  @retval
    FALSE  on success
+  @retval
    TRUE   on error
 */
@@ -2196,18 +2214,17 @@ sp_head::restore_thd_mem_root(THD *thd)
 }
-/*
+/**
-  Check if a user has access right to a routine
+  Check if a user has access right to a routine.
-  SYNOPSIS
+  @param thd		    Thread handler
-    check_show_routine_access()
+  @param sp		    SP
-    thd			Thread handler
+  @param full_access       Set to 1 if the user has SELECT right to the
-    sp			SP
-    full_access		Set to 1 if the user has SELECT right to the
                           'mysql.proc' able or is the owner of the routine
-  RETURN
+  @retval
-    0  ok
+    false ok
-    1  error
+  @retval
+    true  error
 */
 bool check_show_routine_access(THD *thd, sp_head *sp, bool *full_access)
@@ -2334,12 +2351,10 @@ sp_head::show_create_routine(THD *thd, int type)
-/*
+/**
-  Add instruction to SP
+  Add instruction to SP.
-  SYNOPSIS
+  @param instr   Instruction
-    sp_head::add_instr()
-    instr   Instruction
 */
 void sp_head::add_instr(sp_instr *instr)
@@ -2357,20 +2372,20 @@ void sp_head::add_instr(sp_instr *instr)
 }
-/*
+/**
  Do some minimal optimization of the code:
-    1) Mark used instructions
+    -# Mark used instructions
-       1.1) While doing this, shortcut jumps to jump instructions
+    -# While doing this, shortcut jumps to jump instructions
-    2) Compact the code, removing unused instructions
+    -# Compact the code, removing unused instructions.
  This is the main mark and move loop; it relies on the following methods
  in sp_instr and its subclasses:
-  opt_mark()           Mark instruction as reachable
+    - opt_mark()         :  Mark instruction as reachable
-  opt_shortcut_jump()  Shortcut jumps to the final destination;
+    - opt_shortcut_jump():  Shortcut jumps to the final destination;
                           used by opt_mark().
-  opt_move()           Update moved instruction
+    - opt_move()         :  Update moved instruction
-  set_destination()    Set the new destination (jump instructions only)
+    - set_destination()  :  Set the new destination (jump instructions only)
 */
 void sp_head::optimize()
@@ -2461,9 +2476,10 @@ sp_head::opt_mark()
 #ifndef DBUG_OFF
-/*
+/**
  Return the routine instructions as a result set.
-  Returns 0 if ok, !=0 on error.
+  @return
+    0 if ok, !=0 on error.
 */
 int
 sp_head::show_routine_code(THD *thd)
@@ -2526,27 +2542,25 @@ sp_head::show_routine_code(THD *thd)
 #endif // ifndef DBUG_OFF
-/*
+/**
  Prepare LEX and thread for execution of instruction, if requested open
  and lock LEX's tables, execute instruction's core function, perform
  cleanup afterwards.
-  SYNOPSIS
+  @param thd           thread context
-    reset_lex_and_exec_core()
+  @param nextp         out - next instruction
-      thd         - thread context
+  @param open_tables   if TRUE then check read access to tables in LEX's table
-      nextp       - out - next instruction
-      open_tables - if TRUE then check read access to tables in LEX's table
                       list and open and lock them (used in instructions which
                       need to calculate some expression and don't execute
                       complete statement).
-      sp_instr    - instruction for which we prepare context, and which core
+  @param sp_instr      instruction for which we prepare context, and which core
                       function execute by calling its exec_core() method.
-  NOTE
+  @note
    We are not saving/restoring some parts of THD which may need this because
    we do this once for whole routine execution in sp_head::execute().
-  RETURN VALUE
+  @return
    0/non-0 - Success/Failure
 */
@@ -3300,6 +3314,11 @@ sp_instr_cpop::print(String *str)
  sp_instr_copen class functions
 */
+/**
+  @todo
+    Assert that we either have an error or a cursor
+*/
 int
 sp_instr_copen::execute(THD *thd, uint *nextp)
 {
@@ -3621,24 +3640,23 @@ uchar *sp_table_key(const uchar *ptr, size_t *plen, my_bool first)
 }
-/*
+/**
  Merge the list of tables used by some query into the multi-set of
  tables used by routine.
-  SYNOPSIS
+  @param thd                 thread context
-    merge_table_list()
+  @param table               table list
-      thd               - thread context
+  @param lex_for_tmp_check   LEX of the query for which we are merging
-      table             - table list
-      lex_for_tmp_check - LEX of the query for which we are merging
                             table list.
-  NOTE
+  @note
    This method will use LEX provided to check whenever we are creating
    temporary table and mark it as such in target multi-set.
-  RETURN VALUE
+  @retval
-    TRUE  - Success
+    TRUE    Success
-    FALSE - Error
+  @retval
+    FALSE   Error
 */
 bool
@@ -3726,27 +3744,26 @@ sp_head::merge_table_list(THD *thd, TABLE_LIST *table, LEX *lex_for_tmp_check)
 }
-/*
+/**
  Add tables used by routine to the table list.
-  SYNOPSIS
-    add_used_tables_to_table_list()
-      thd                    [in]     Thread context
-      query_tables_last_ptr  [in/out] Pointer to the next_global member of
-                                      last element of the list where tables
-                                      will be added (or to its root).
-      belong_to_view         [in]     Uppermost view which uses this routine,
-                                      0 if none.
-  DESCRIPTION
    Converts multi-set of tables used by this routine to table list and adds
    this list to the end of table list specified by 'query_tables_last_ptr'.
    Elements of list will be allocated in PS memroot, so this list will be
    persistent between PS executions.
-  RETURN VALUE
+  @param[in] thd                        Thread context
-    TRUE - if some elements were added, FALSE - otherwise.
+  @param[in,out] query_tables_last_ptr  Pointer to the next_global member of
+    last element of the list where tables
+    will be added (or to its root).
+  @param[in] belong_to_view             Uppermost view which uses this routine,
+    0 if none.
+  @retval
+    TRUE    if some elements were added
+  @retval
+    FALSE   otherwise.
 */
 bool
@@ -3816,7 +3833,7 @@ sp_head::add_used_tables_to_table_list(THD *thd,
 }
-/*
+/**
  Simple function for adding an explicetly named (systems) table to
  the global table list, e.g. "mysql", "proc".
 */