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()
+  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.
 
-  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 ;)
-
- RETURN
-	0	ok
-	1	Error   
+#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.
+
+  @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
-   0	ok
-   1	Could not open file
-   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
+    0	ok
+  @retval
+    1	Could not open file
+  @retval
+    2    Could not stat file
+  @retval
+    3    Could not allocate data for read.  Could not read file
 */
 
 int readfrm(const char *name, uchar **frmdata, size_t *len)
@@ -87,18 +91,16 @@ 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
-   0	ok
-   2    Could not write file
+  @retval
+    0	ok
+  @retval
+    2    Could not write file
 */
 
 int writefrm(const char *name, const uchar *frmdata, size_t len)

sql/field_conv.cc

@@ -14,11 +14,15 @@
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
 
-/*
- Functions to copy data to or from fields
- This could be done with a single short function but opencoding this
- gives much more speed.
- */
+/**
+  @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,22 +133,21 @@ set_field_to_null(Field *field)
 }
 
 
-/*
-  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
-			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
-    0		Field could take 0 or an automatic conversion was used
-    -1		Field could not take NULL and no conversion was used.
-		If no_conversion was not set, an error message is printed
+/**
+  Set field to NULL or TIMESTAMP or to next auto_increment number.
+
+  @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.
+
+  @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
 */
 
 int
@@ -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,12 +66,14 @@ 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
+    use instead to_upper_lex, special array 
+    (substitute chars) without skip codes..
+@todo
+    try use reverse order of comparing..
 
-TODO:
-1. use instead to_upper_lex, special array 
-   (substitute chars) without skip codes..
-2. try use reverse order of comparing..
-       
 */
 
 #define NO_YACC_SYMBOLS

sql/hostname.cc

@@ -14,9 +14,14 @@
    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
-  checked that they doesn't resemble an ip.
+/**
+  @file
+
+  @brief
+  Get hostname for an IP.
+
+    Hostnames are checked with reverse name lookup and
+    checked that they doesn't resemble an ip.
 */
 
 #include "mysql_priv.h"

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/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/mysqld_suffix.h

@@ -13,8 +13,11 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
-  Set MYSQL_SERVER_SUFFIX_STR
+/**
+  @file
+
+  Set MYSQL_SERVER_SUFFIX_STR.
+
   The following code is quite ugly as there is no portable way to easily set a
   string to the value of a macro
 */