Doxygenized comments.

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
-    The cached buffer can be sent as it is with 'net_flush()'.
+  @param net		Network handler
+  @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
-    my_net_skip_rest()
-    net		Communication handle
-    remain	Bytes to read
-    alarmed	Parameter for thr_alarm()
-    alarm_buff	Parameter for thr_alarm()
+  @param net		Communication handle
+  @param remain	Bytes to read
+  @param alarmed	Parameter for thr_alarm()
+  @param 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
-  Returns length of packet.  Long packets are handled by my_net_read().
+/**
+  Reads one packet to net->buff + net->where_b.
+  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 @@ end:
 }
 
 
-/*
+/**
   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.
 */

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
-	1  Can't open the Service manager
-	2  Failed to create service
- -------------------------------------------------------------------------- */
+  - 0  success
+  - 1  Can't open the Service manager
+  - 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
-	1  Can't open the Service manager
-	2  Failed to locate service
-	3  Failed to delete service
- -------------------------------------------------------------------------- */
+  - 0  success
+  - 1  Can't open the Service manager
+  - 2  Failed to locate 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
-		  service manager to start the service
- -------------------------------------------------------------------------- */
+/**
+  This is the function that is called from the
+  service manager to start the service.
+*/
+
 
 void NTService::ServiceMain(DWORD argc, LPTSTR *argv)
 {
@@ -264,9 +274,9 @@ error:
   return;
 }
 
-/* ------------------------------------------------------------------------
-   StartService() - starts the appliaction thread
- -------------------------------------------------------------------------- */
+/**
+  starts the appliaction thread.
+*/
 
 BOOL NTService::StartService()
 {

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
-    opt_sum_query()
-    tables                list of leaves of join table tree
-    all_fields            All fields to be returned
-    conds                 WHERE clause
+  @param tables                list of leaves of join table tree
+  @param all_fields            All fields to be returned
+  @param 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
-       wait timeout happens, for example
+  @retval
+    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
-    simple_pred()
-    func_item        Predicate item
-    args        out: Here we store the field followed by constants
-    inv_order   out: Is set to 1 if the predicate is of the form
+  @param func_item        Predicate item
+  @param[out] args        Here we store the field followed by constants
+  @param[out] inv_order   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
-    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
+     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
-    reckey_in_range()
-    max_fl      in:     0 for MIN(field) / 1 for MAX(field)
-    ref         in:     Reference to the key value and info
-    field       in:     Field used the MIN/MAX expression
-    cond        in:     WHERE condition
-    range_fl    in:     Says whether there is a condition to to be checked
-    prefix_len  in:     Length of the constant part of the key
+  @param[in] max_fl         0 for MIN(field) / 1 for MAX(field)
+  @param[in] ref            Reference to the key value and info
+  @param[in] field          Field used the MIN/MAX expression
+  @param[in] cond           WHERE condition
+  @param[in] range_fl       Says whether there is a condition to to be checked
+  @param[in] prefix_len     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
-  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
+/**
+  Check whether {MAX|MIN}(field) is in range specified by conditions.
 
-  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
 */
 

sql/procedure.cc

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

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
-    send_ok()
-    thd			Thread handler
-    affected_rows	Number of rows changed by statement
-    id			Auto_increment id for first row (if used)
-    message		Message to send to the client (Used by mysql_status)
-
-  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
+  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
-    message		Stored as packed length (1-9 bytes) + message
-			Is not stored if no message
+  - warning_count	: Stored in 2 bytes; New in 4.1 protocol
+  - message		: Stored as packed length (1-9 bytes) + 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
-
-  SYNOPSIS
-    send_eof()
-    thd			Thread handler
-    no_flush		Set to 1 if there will be more data to the client,
-			like in send_fields().
+/**
+  Send eof (= end of result set) to the client.
 
-  DESCRIPTION
-    The eof packet has the following structure
+  The eof packet has the following structure:
 
-    254			Marker (1 byte)
-    warning_count	Stored in 2 bytes; New in 4.1 protocol
-    status_flag		Stored in 2 bytes;
-			For flags like SERVER_MORE_RESULTS_EXISTS
+  - 254		: Marker (1 byte)
+  - warning_count	: Stored in 2 bytes; New in 4.1 protocol
+  - status_flag	: Stored in 2 bytes;
+  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
-  ulong for 0..4294967296
-  ulonglong for bigger numbers.
+  - uint for 0..65536
+  - ulong for 0..4294967296
+  - ulonglong for bigger numbers.
 */
 
 static uchar *net_store_length_fast(uchar *packet, uint length)
@@ -530,27 +531,26 @@ bool Protocol::flush()
 #endif
 }
 
-/*
-  Send name and type of result to client.
+#ifndef EMBEDDED_LIBRARY
 
-  SYNOPSIS
-    send_fields()
-    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
+/**
+  Send name and type of result to client.
 
-  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
-    store()
-    from	NullS or \0 terminated string
+  @param 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.
 */

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
-    rr_index_first()
-    info  	Scan info
+  @param 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
-
-  SYNOPSIS
-    rr_unpack_from_tempfile()
-    info                Reference to the context including record descriptors
+/**
+  Read a result set record from a temporary file after sorting.
 
-  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
-     0 - Record successfully read.
-    -1 - There is no record to be read anymore. 
+  @param info          Reference to the context including record descriptors
+
+  @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
-
-  SYNOPSIS
-    rr_unpack_from_buffer()
-    info                   Reference to the context including record descriptors
+/**
+  Read a result set record from a buffer after sorting.
 
-  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
-     0 - Record successfully read.
-    -1 - There is no record to be read anymore. 
+  @param info          Reference to the context including record descriptors
+
+  @retval
+    0   Record successfully read.
+  @retval
+    -1   There is no record to be read anymore.
 */
 
 static int rr_unpack_from_buffer(READ_RECORD *info)

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 @@ err:
 }
 
 
-/*
-  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
-    update_slave_list()
-    mysql           pre-existing connection to the master
-    mi              master info
+  @param mysql           pre-existing connection to the master
+  @param 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)

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:
-    - 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).
-
-  TODO:
-    - Add full support for the variable character_set (for 4.1)
+  @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 @@ err:
 }
 
 
-/*
-  Return an Item for a variable.  Used with @@[global.]variable_name
-  If type is not given, return local value if exists, else global
+/**
+  Return an Item for a variable.
+
+  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 @@ end:
 }
 
 
+/**
+  @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
-
-  SYNOPSIS
-    get_tmpdir()
-    thd		thread handle
+/**
+  Get the tmpdir that was specified or chosen by default.
 
-  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
-    find_option()
-    opt		option structure array to search in
-    name	variable name
+  @param opt	option structure array to search in
+  @param 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
-    intern_find_sys_var()
-    str		Name of system variable to find
-    length	Length of variable.  zero means that we should use strlen()
+  @param str	   Name of system variable to find
+  @param 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
-
-  SYNOPSIS
-
-  sql_set
-    THD		Thread id
-    set_var	List of variables to update
+/**
+  Execute update of all variables.
 
-  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 @@ err:
 }
 
 
-/*
-  Say if all variables set by a SET support the ONE_SHOT keyword (currently,
-  only character set and collation do; later timezones will).
-
-  SYNOPSIS
+/**
+  Say if all variables set by a SET support the ONE_SHOT keyword
+  (currently, only character set and collation do; later timezones
+  will).
 
-  not_all_support_one_shot
-    set_var	List of variables to update
+  @param var_list	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
-    set_var::light_check()
-    thd		thread handler
+  @param 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
-    set_var_user::light_check()
-    thd		thread handler
+  @param 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
-    thd   in  thread handler
-    val   in  sql_mode value
-    rep   out pointer pointer to string with sql_mode representation
+  @param[in]  thd    thread handler
+  @param[in]  val    sql_mode value
+  @param[out] len    pointer on length of string
+
+  @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)
 {