Merge bk-internal.mysql.com:/home/bk/mysql-5.1-maint

into  zippy.cornsilk.net:/home/cmiller/work/mysql/mysql-5.1-maint

sql/derror.cc

@@ -14,7 +14,12 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* Read language depeneded messagefile */
+/**
+  @file
+
+  @brief
+  Read language depeneded messagefile
+*/
 
 #include "mysql_priv.h"
 #include "mysys_err.h"
@@ -23,20 +28,17 @@ static bool read_texts(const char *file_name,const char ***point,
 		       uint error_messages);
 static void init_myfunc_errs(void);
 
-/*
+/**
   Read messages from errorfile.
 
-  SYNOPSIS
-    init_errmessage()
-
-  DESCRIPTION
   This function can be called multiple times to reload the messages.
   If it fails to load the messages, it will fail softly by initializing
   the errmesg pointer to an array of empty strings or by keeping the
   old array if it exists.
 
-  RETURN
+  @retval
     FALSE       OK
+  @retval
     TRUE        Error
 */
 
@@ -75,7 +77,14 @@ bool init_errmessage(void)
 }
 
 
-	/* Read text from packed textfile in language-directory */
+/**
+  Read text from packed textfile in language-directory.
+
+  If we can't read messagefile then it's panic- we can't continue.
+
+  @todo
+    Convert the character set to server system character set
+*/
 
 static bool read_texts(const char *file_name,const char ***point,
 		       uint error_messages)
@@ -178,7 +187,9 @@ Check that the above file is the right version for this program!",
 } /* read_texts */
 
 
-	/* Initiates error-messages used by my_func-library */
+/**
+  Initiates error-messages used by my_func-library.
+*/
 
 static void init_myfunc_errs()
 {

sql/des_key_file.cc

@@ -21,17 +21,18 @@
 struct st_des_keyschedule des_keyschedule[10];
 uint   des_default_key;
 
-/*
- Function which loads DES keys from plaintext file into memory on MySQL
- server startup and on command FLUSH DES_KEY_FILE.
- Blame tonu@spam.ee on bugs ;)
+#define des_cs	&my_charset_latin1
+
+/**
+  Load DES keys from plaintext file into
+  memory on MySQL server startup and on command FLUSH DES_KEY_FILE.
 
- RETURN
+  @retval
     0  ok
+  @retval
     1  Error   
 */
 
-#define des_cs	&my_charset_latin1
 
 bool
 load_des_key_file(const char *file_name)

sql/discover.cc

@@ -14,29 +14,33 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* Functions for discover of frm file from handler */
+/**
+  @file
+
+  @brief
+  Functions for discover of frm file from handler
+*/
 
 #include "mysql_priv.h"
 #include <my_dir.h>
 
-/*
-  Read the contents of a .frm file
+/**
+  Read the contents of a .frm file.
 
-  SYNOPSIS
-    readfrm()
+  frmdata and len are set to 0 on error.
 
-    name           path to table-file "db/name"
-    frmdata        frm data
-    len            length of the read frmdata
+  @param name           path to table-file "db/name"
+  @param frmdata        frm data
+  @param len            length of the read frmdata
 
-  RETURN VALUES
+  @retval
     0	ok
+  @retval
     1	Could not open file
+  @retval
     2    Could not stat file
-   3    Could not allocate data for read
-        Could not read file
-
-   frmdata and len are set to 0 on error
+  @retval
+    3    Could not allocate data for read.  Could not read file
 */
 
 int readfrm(const char *name, uchar **frmdata, size_t *len)
@@ -87,17 +91,15 @@ int readfrm(const char *name, uchar **frmdata, size_t *len)
 
 /*
   Write the content of a frm data pointer 
-  to a frm file
-
-  SYNOPSIS
-    writefrm()
+  to a frm file.
 
-    name           path to table-file "db/name"
-    frmdata        frm data
-    len            length of the frmdata
+  @param name           path to table-file "db/name"
+  @param frmdata        frm data
+  @param len            length of the frmdata
 
-  RETURN VALUES
+  @retval
     0	ok
+  @retval
     2    Could not write file
 */
 

sql/field_conv.cc

@@ -14,11 +14,15 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/*
+/**
+  @file
+
+  @brief
   Functions to copy data to or from fields
+
     This could be done with a single short function but opencoding this
     gives much more speed.
- */
+*/
 
 #include "mysql_priv.h"
 #include <m_ctype.h>
@@ -129,20 +133,19 @@ set_field_to_null(Field *field)
 }
 
 
-/*
-  Set field to NULL or TIMESTAMP or to next auto_increment number
+/**
+  Set field to NULL or TIMESTAMP or to next auto_increment number.
 
-  SYNOPSIS
-    set_field_to_null_with_conversions()
-    field		Field to update
-    no_conversion	Set to 1 if we should return 1 if field can't
+  @param field           Field to update
+  @param no_conversions  Set to 1 if we should return 1 if field can't
                          take null values.
                          If set to 0 we will do store the 'default value'
                          if the field is a special field. If not we will
                          give an error.
 
-  RETURN VALUES
+  @retval
     0    Field could take 0 or an automatic conversion was used
+  @retval
     -1   Field could not take NULL and no conversion was used.
     If no_conversion was not set, an error message is printed
 */
@@ -283,7 +286,7 @@ static void do_conv_blob(Copy_field *copy)
 					 copy->tmp.charset());
 }
 
-/* Save blob in copy->tmp for GROUP BY */
+/** Save blob in copy->tmp for GROUP BY. */
 
 static void do_save_blob(Copy_field *copy)
 {
@@ -352,9 +355,9 @@ static void do_field_decimal(Copy_field *copy)
 }
 
 
-/*
+/**
   string copy for single byte characters set when to string is shorter than
-  from string
+  from string.
 */
 
 static void do_cut_string(Copy_field *copy)
@@ -374,9 +377,9 @@ static void do_cut_string(Copy_field *copy)
 }
 
 
-/*
+/**
   string copy for multi byte characters set when to string is shorter than
-  from string
+  from string.
 */
 
 static void do_cut_string_complex(Copy_field *copy)
@@ -507,7 +510,7 @@ static void do_varstring2_mb(Copy_field *copy)
 ** The different functions that fills in a Copy_field class
 ***************************************************************************/
 
-/*
+/**
   copy of field to maybe null string.
   If field is null then the all bytes are set to 0.
   if field is not null then the first byte is set to 1 and the rest of the
@@ -748,7 +751,7 @@ Copy_field::get_copy_func(Field *to,Field *from)
 }
 
 
-/* Simple quick field convert that is called on insert */
+/** Simple quick field convert that is called on insert. */
 
 int field_conv(Field *to,Field *from)
 {

sql/gen_lex_hash.cc

@@ -13,8 +13,11 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
+/**
+  @file
 
+  @details
+@verbatim
 The idea of presented algorithm see in 
 "The Art of Computer Programming" by Donald E. Knuth
 Volume 3 "Sorting and searching"
@@ -63,11 +66,13 @@ for optimization, link is the 16-bit index in 'symbols' or 'sql_functions'
 or search-array..
 
 So, we can read full search-structure as 32-bit word
+@endverbatim
 
-TODO:
-1. use instead to_upper_lex, special array 
+@todo
+    use instead to_upper_lex, special array 
     (substitute chars) without skip codes..
-2. try use reverse order of comparing..
+@todo
+    try use reverse order of comparing..
 
 */
 

sql/hostname.cc

@@ -14,8 +14,13 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/*
-  Get hostname for an IP.  Hostnames are checked with reverse name lookup and
+/**
+  @file
+
+  @brief
+  Get hostname for an IP.
+
+    Hostnames are checked with reverse name lookup and
     checked that they doesn't resemble an ip.
 */
 

sql/init.cc

@@ -14,7 +14,12 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* Init and dummy functions for interface with unireg */
+/**
+  @file
+
+  @brief
+  Init and dummy functions for interface with unireg
+*/
 
 #include "mysql_priv.h"
 #include <m_ctype.h>

sql/item_buff.cc

@@ -14,12 +14,17 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* Buffers to save and compare item values */
+/**
+  @file
+
+  @brief
+  Buffers to save and compare item values
+*/
 
 #include "mysql_priv.h"
 
-/*
-** Create right type of Cached_item for an item
+/**
+  Create right type of Cached_item for an item.
 */
 
 Cached_item *new_Cached_item(THD *thd, Item *item)
@@ -45,9 +50,11 @@ Cached_item *new_Cached_item(THD *thd, Item *item)
 
 Cached_item::~Cached_item() {}
 
-/*
-** Compare with old value and replace value with new value
-** Return true if values have changed
+/**
+  Compare with old value and replace value with new value.
+
+  @return
+    Return true if values have changed
 */
 
 Cached_item_str::Cached_item_str(THD *thd, Item *arg)

sql/item_create.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 */
 
-/* Functions to create an item. Used by sql_yacc.yy */
+/**
+  @file
+
+  @brief
+  Functions to create an item. Used by sql_yac.yy
+*/
 
 #include "mysql_priv.h"
 #include "item_create.h"

sql/item_geofunc.cc

@@ -14,7 +14,12 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* This file defines all spatial functions */
+/**
+  @file
+
+  @brief
+  This file defines all spatial functions
+*/
 
 #ifdef USE_PRAGMA_IMPLEMENTATION
 #pragma implementation				// gcc: Class implementation
@@ -356,7 +361,7 @@ String *Item_func_point::val_str(String *str)
 }
 
 
-/*
+/**
   Concatenates various items into various collections
   with checkings for valid wkb type of items.
   For example, MultiPoint can be a collection of Points only.
@@ -538,6 +543,10 @@ longlong Item_func_isempty::val_int()
 }
 
 
+/**
+  @todo
+    Ramil or Holyfoot, add real IsSimple calculation
+*/
 longlong Item_func_issimple::val_int()
 {
   DBUG_ASSERT(fixed == 1);

sql/item_row.cc

@@ -15,13 +15,18 @@
 
 #include "mysql_priv.h"
 
-/*
+/**
   Row items used for comparing rows and IN operations on rows:
 
+  @verbatim
   (a, b, c) > (10, 10, 30)
   (a, b, c) = (select c, d, e, from t1 where x=12)
   (a, b, c) IN ((1,2,2), (3,4,5), (6,7,8)
   (a, b, c) IN (select c, d, e, from t1)
+  @endverbatim
+
+  @todo
+    think placing 2-3 component items in item (as it done for function
 */
 
 Item_row::Item_row(List<Item> &arg):

sql/item_strfunc.cc

@@ -14,9 +14,15 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/* This file defines all string functions
-** Warning: Some string functions doesn't always put and end-null on a String
-** (This shouldn't be needed)
+/**
+  @file
+
+  @brief
+  This file defines all string functions
+
+  @warning
+    Some string functions don't always put and end-null on a String.
+    (This shouldn't be needed)
 */
 
 #ifdef USE_PRAGMA_IMPLEMENTATION
@@ -267,9 +273,9 @@ void Item_func_aes_decrypt::fix_length_and_dec()
 }
 
 
-/*
+/**
   Concatenate args with the following premises:
-  If only one arg (which is ok), return value of arg
+  If only one arg (which is ok), return value of arg;
   Don't reallocate val_str() if not absolute necessary.
 */
 
@@ -425,13 +431,15 @@ void Item_func_concat::fix_length_and_dec()
   max_length= (ulong) max_result_length;
 }
 
-/*
+/**
+  @details
   Function des_encrypt() by tonu@spam.ee & monty
   Works only if compiled with OpenSSL library support.
-  This returns a binary string where first character is CHAR(128 | key-number).
+  @return
+    A binary string where first character is CHAR(128 | key-number).
     If one uses a string key key_number is 127.
     Encryption result is longer than original by formula:
-  new_length= org_length + (8-(org_length % 8))+1
+  @code new_length= org_length + (8-(org_length % 8))+1 @endcode
 */
 
 String *Item_func_des_encrypt::val_str(String *str)
@@ -604,7 +612,7 @@ String *Item_func_des_decrypt::val_str(String *str)
 }
 
 
-/*
+/**
   concat with separator. First arg is the separator
   concat_ws takes at least two arguments.
 */
@@ -826,12 +834,14 @@ void Item_func_reverse::fix_length_and_dec()
   max_length = args[0]->max_length;
 }
 
-/*
-** Replace all occurences of string2 in string1 with string3.
-** Don't reallocate val_str() if not needed
-*/
+/**
+  Replace all occurences of string2 in string1 with string3.
+
+  Don't reallocate val_str() if not needed.
 
-/* TODO: Fix that this works with binary strings when using USE_MB */
+  @todo
+    Fix that this works with binary strings when using USE_MB 
+*/
 
 String *Item_func_replace::val_str(String *str)
 {
@@ -1796,8 +1806,9 @@ String *Item_func_database::val_str(String *str)
 }
 
 
-/*
-  TODO: make USER() replicate properly (currently it is replicated to "")
+/**
+  @todo
+  make USER() replicate properly (currently it is replicated to "")
 */
 bool Item_func_user::init(const char *user, const char *host)
 {
@@ -1857,7 +1868,7 @@ void Item_func_soundex::fix_length_and_dec()
 }
 
 
-/*
+/**
   If alpha, map input letter to soundex code.
   If not alpha and remove_garbage is set then skip to next char
   else return 0
@@ -2001,9 +2012,10 @@ String *Item_func_soundex::val_str(String *str)
 }
 
 
-/*
-** Change a number to format '3,333,333,333.000'
-** This should be 'internationalized' sometimes.
+/**
+  Change a number to format '3,333,333,333.000'.
+
+  This should be 'internationalized' sometimes.
 */
 
 const int FORMAT_MAX_DECIMALS= 30;
@@ -2022,8 +2034,9 @@ void Item_func_format::fix_length_and_dec()
 }
 
 
-/*
-  TODO: This needs to be fixed for multi-byte character set where numbers
+/**
+  @todo
+  This needs to be fixed for multi-byte character set where numbers
   are stored in more than one byte
 */
 
@@ -2370,9 +2383,9 @@ void Item_func_repeat::fix_length_and_dec()
   }
 }
 
-/*
-** Item_func_repeat::str is carefully written to avoid reallocs
-** as much as possible at the cost of a local buffer
+/**
+  Item_func_repeat::str is carefully written to avoid reallocs
+  as much as possible at the cost of a local buffer
 */
 
 String *Item_func_repeat::val_str(String *str)
@@ -2848,7 +2861,7 @@ String *Item_func_hex::val_str(String *str)
   return &tmp_value;
 }
 
-  /* Convert given hex string to a binary string */
+  /** Convert given hex string to a binary string. */
 
 String *Item_func_unhex::val_str(String *str)
 {
@@ -3081,27 +3094,27 @@ String* Item_func_inet_ntoa::val_str(String* str)
 }
 
 
-/*
+#define get_esc_bit(mask, num) (1 & (*((mask) + ((num) >> 3))) >> ((num) & 7))
+
+/**
   QUOTE() function returns argument string in single quotes suitable for
   using in a SQL statement.
 
-  DESCRIPTION
-    Adds a \ before all characters that needs to be escaped in a SQL string.
+  Adds a \\ before all characters that needs to be escaped in a SQL string.
   We also escape '^Z' (END-OF-FILE in windows) to avoid probelms when
   running commands from a file in windows.
 
-    This function is very useful when you want to generate SQL statements
+  This function is very useful when you want to generate SQL statements.
 
-  NOTE
+  @note
     QUOTE(NULL) returns the string 'NULL' (4 letters, without quotes).
 
-  RETURN VALUES
+  @retval
     str	   Quoted string
+  @retval
     NULL	   Out of memory.
 */
 
-#define get_esc_bit(mask, num) (1 & (*((mask) + ((num) >> 3))) >> ((num) & 7))
-
 String *Item_func_quote::val_str(String *str)
 {
   DBUG_ASSERT(fixed == 1);
@@ -3347,8 +3360,10 @@ static uint nanoseq;
 static ulonglong uuid_time=0;
 static char clock_seq_and_node_str[]="-0000-000000000000";
 
-/* number of 100-nanosecond intervals between
-   1582-10-15 00:00:00.00 and 1970-01-01 00:00:00.00 */
+/**
+  number of 100-nanosecond intervals between
+  1582-10-15 00:00:00.00 and 1970-01-01 00:00:00.00.
+*/
 #define UUID_TIME_OFFSET ((ulonglong) 141427 * 24 * 60 * 60 * 1000 * 10 )
 
 #define UUID_VERSION      0x1000

sql/mf_iocache.cc

@@ -13,8 +13,11 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
-  Cashing of files with only does (sequential) read or writes of fixed-
+/**
+  @file
+
+  @details
+  Caching of files with only does (sequential) read or writes of fixed-
   length records. A read isn't allowed to go over file-length. A read is ok
   if it ends at file-length and next read can try to read after file-length
   (and get a EOF-error).
@@ -34,11 +37,15 @@
 
 extern "C" {
 
-	/*
-	** Read buffered from the net.
-	** Returns 1 if can't read requested characters
-	** Returns 0 if record read
-	*/
+/**
+  Read buffered from the net.
+
+  @retval
+    1   if can't read requested characters
+  @retval
+    0   if record read
+*/
+
 
 int _my_b_net_read(register IO_CACHE *info, uchar *Buffer,
 		   size_t Count __attribute__((unused)))

sql/my_decimal.cc

@@ -18,17 +18,15 @@
 
 
 #ifndef MYSQL_CLIENT
-/*
-  report result of decimal operation
+/**
+  report result of decimal operation.
 
-  SYNOPSIS
-    decimal_operation_results()
-    result  decimal library return code (E_DEC_* see include/decimal.h)
+  @param result  decimal library return code (E_DEC_* see include/decimal.h)
 
-  TODO
+  @todo
     Fix error messages
 
-  RETURN
+  @return
     result
 */
 

sql/my_decimal.h

@@ -13,7 +13,9 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
+/**
+  @file
+
   It is interface module to fixed precision decimals library.
 
   Most functions use 'uint mask' as parameter, if during operation error
@@ -34,14 +36,14 @@ C_MODE_END
 #define DECIMAL_LONG_DIGITS 10
 #define DECIMAL_LONG3_DIGITS 8
 
-/* maximum length of buffer in our big digits (uint32) */
+/** maximum length of buffer in our big digits (uint32). */
 #define DECIMAL_BUFF_LENGTH 9
 
 /* the number of digits that my_decimal can possibly contain */
 #define DECIMAL_MAX_POSSIBLE_PRECISION (DECIMAL_BUFF_LENGTH * 9)
 
 
-/*
+/**
   maximum guaranteed precision of number in decimal digits (number of our
   digits * number of decimal digits in one our big digit - number of decimal
   digits in one our big digit decreased by 1 (because we always put decimal
@@ -51,13 +53,14 @@ C_MODE_END
 #define DECIMAL_MAX_SCALE 30
 #define DECIMAL_NOT_SPECIFIED 31
 
-/*
+/**
   maximum length of string representation (number of maximum decimal
   digits + 1 position for sign + 1 position for decimal point)
 */
 #define DECIMAL_MAX_STR_LENGTH (DECIMAL_MAX_POSSIBLE_PRECISION + 2)
-/*
-  maximum size of packet length
+
+/**
+  maximum size of packet length.
 */
 #define DECIMAL_MAX_FIELD_SIZE DECIMAL_MAX_PRECISION
 
@@ -78,11 +81,12 @@ inline int my_decimal_int_part(uint precision, uint decimals)
 }
 
 
-/*
-  my_decimal class limits 'decimal_t' type to what we need in MySQL
+/**
+  my_decimal class limits 'decimal_t' type to what we need in MySQL.
+
   It contains internally all necessary space needed by the instance so
   no extra memory is needed. One should call fix_buffer_pointer() function
-  when he moves my_decimal objects in memory
+  when he moves my_decimal objects in memory.
 */
 
 class my_decimal :public decimal_t
@@ -384,7 +388,10 @@ int my_decimal_mod(uint mask, my_decimal *res, const my_decimal *a,
 }
 
 
-/* Returns -1 if a<b, 1 if a>b and 0 if a==b */
+/**
+  @return
+    -1 if a<b, 1 if a>b and 0 if a==b
+*/
 inline
 int my_decimal_cmp(const my_decimal *a, const my_decimal *b)
 {