Consistently use doxygen comments in class handler.

sql/handler.h

@@ -959,11 +959,11 @@ uint calculate_key_len(TABLE *, uint, const uchar *, key_part_map);
 */
 #define make_prev_keypart_map(N) (((key_part_map)1 << (N)) - 1)
 
-/*
+/**
   The handler class is the interface for dynamically loadable
   storage engines. Do not add ifdefs and take care when adding or
   changing virtual functions to avoid vtable confusion
- */
+*/
 
 class handler :public Sql_alloc
 {
@@ -981,7 +981,7 @@ public:
 
   virtual int index_init(uint idx, bool sorted) { active_index=idx; return 0; }
   virtual int index_end() { active_index=MAX_KEY; return 0; }
-  /*
+  /**
     rnd_init() can be called two times without rnd_end() in between
     (it only makes sense if scan=1).
     then the second call should prepare for the new table scan (e.g
@@ -1006,13 +1006,13 @@ public:
 
   ha_statistics stats;
 
-  /* The following are for read_multi_range */
+  /** The following are for read_multi_range */
   bool multi_range_sorted;
   KEY_MULTI_RANGE *multi_range_curr;
   KEY_MULTI_RANGE *multi_range_end;
   HANDLER_BUFFER *multi_range_buffer;
 
-  /* The following are for read_range() */
+  /** The following are for read_range() */
   key_range save_end_range, *end_range;
   KEY_PART_INFO *range_key_part;
   int key_compare_result_on_equal;
@@ -1021,14 +1021,14 @@ public:
   uint errkey;				/* Last dup key */
   uint key_used_on_scan;
   uint active_index;
-  /* Length of ref (1-8 or the clustered key length) */
+  /** Length of ref (1-8 or the clustered key length) */
   uint ref_length;
   FT_INFO *ft_handler;
   enum {NONE=0, INDEX, RND} inited;
   bool locked;
   bool implicit_emptied;                /* Can be !=0 only if HEAP */
   const COND *pushed_cond;
-  /*
+  /**
     next_insert_id is the next value which should be inserted into the
     auto_increment column: in a inserting-multi-row statement (like INSERT
     SELECT), for the first row where the autoinc value is not specified by the
@@ -1038,14 +1038,14 @@ public:
     get_auto_increment().
   */
   ulonglong next_insert_id;
-  /*
+  /**
     insert id for the current row (*autogenerated*; if not
     autogenerated, it's 0).
     At first successful insertion, this variable is stored into
     THD::first_successful_insert_id_in_cur_stmt.
   */
   ulonglong insert_id_for_cur_row;
-  /*
+  /**
     Interval returned by get_auto_increment() and being consumed by the
     inserter.
   */
@@ -1066,7 +1066,7 @@ public:
     /* TODO: DBUG_ASSERT(inited == NONE); */
   }
   virtual handler *clone(MEM_ROOT *mem_root);
-  /* This is called after create to allow us to set up cached variables */
+  /** This is called after create to allow us to set up cached variables */
   void init()
   {
     cached_table_flags= table_flags();
@@ -1092,7 +1092,7 @@ public:
   { return (ha_table_flags() & HA_NO_TRANSACTIONS) == 0; }
   virtual uint extra_rec_buf_length() const { return 0; }
 
-  /*
+  /**
     This method is used to analyse the error to see whether the error
     is ignorable or not, certain handlers can have more error that are
     ignorable than others. E.g. the partition handler can get inserts
@@ -1112,12 +1112,12 @@ public:
     return TRUE;
   }
 
-  /*
+  /**
     Number of rows in table. It will only be called if
     (table_flags() & (HA_HAS_RECORDS | HA_STATS_RECORDS_IS_EXACT)) != 0
   */
   virtual ha_rows records() { return stats.records; }
-  /*
+  /**
     Return upper bound of current number of records in the table
     (max. of how many records one will retrieve when doing a full table scan)
     If upper bound is not known, HA_POS_ERROR should be returned as a max
@@ -1126,7 +1126,7 @@ public:
   virtual ha_rows estimate_rows_upper_bound()
   { return stats.records+EXTRA_RECORDS; }
 
-  /*
+  /**
     Get the row type from the storage engine.  If this method returns
     ROW_TYPE_NOT_USED, the information in HA_CREATE_INFO should be used.
   */
@@ -1174,7 +1174,7 @@ public:
   }
   Table_flags ha_table_flags() const { return cached_table_flags; }
 
-  /*
+  /**
     Signal that the table->read_set and table->write_set table maps changed
     The handler is allowed to set additional bits in the above map in this
     call. Normally the handler should ignore all calls until we have done
@@ -1186,7 +1186,7 @@ public:
   virtual int open(const char *name, int mode, uint test_if_locked)=0;
   virtual int close(void)=0;
 
-  /*
+  /**
     These functions represent the public interface to *users* of the
     handler class, hence they are *not* virtual. For the inheritance
     interface, see the (private) functions write_row(), update_row(),
@@ -1197,36 +1197,28 @@ public:
   int ha_update_row(const uchar * old_data, uchar * new_data);
   int ha_delete_row(const uchar * buf);
 
-  /*
-    SYNOPSIS
-      start_bulk_update()
-    RETURN
-      0   Bulk update used by handler
-      1   Bulk update not used, normal operation used
+  /**
+    @retval  0   Bulk update used by handler
+    @retval  1   Bulk update not used, normal operation used
   */
   virtual bool start_bulk_update() { return 1; }
-  /*
-    SYNOPSIS
-      start_bulk_delete()
-    RETURN
-      0   Bulk delete used by handler
-      1   Bulk delete not used, normal operation used
+  /**
+    @retval  0   Bulk delete used by handler
+    @retval  1   Bulk delete not used, normal operation used
   */
   virtual bool start_bulk_delete() { return 1; }
-  /*
-    SYNOPSIS
+  /**
     This method is similar to update_row, however the handler doesn't need
     to execute the updates at this point in time. The handler can be certain
     that another call to bulk_update_row will occur OR a call to
     exec_bulk_update before the set of updates in this query is concluded.
 
-      bulk_update_row()
-        old_data       Old record
-        new_data       New record
-        dup_key_found  Number of duplicate keys found
-    RETURN
-      0   Bulk delete used by handler
-      1   Bulk delete not used, normal operation used
+    @param    old_data       Old record
+    @param    new_data       New record
+    @param    dup_key_found  Number of duplicate keys found
+
+    @retval  0   Bulk delete used by handler
+    @retval  1   Bulk delete not used, normal operation used
   */
   virtual int bulk_update_row(const uchar *old_data, uchar *new_data,
                               uint *dup_key_found)
@@ -1234,53 +1226,43 @@ public:
     DBUG_ASSERT(FALSE);
     return HA_ERR_WRONG_COMMAND;
   }
-  /*
-    SYNOPSIS
+  /**
     After this call all outstanding updates must be performed. The number
     of duplicate key errors are reported in the duplicate key parameter.
     It is allowed to continue to the batched update after this call, the
     handler has to wait until end_bulk_update with changing state.
 
-      exec_bulk_update()
-        dup_key_found       Number of duplicate keys found
-    RETURN
-      0           Success
-      >0          Error code
+    @param    dup_key_found       Number of duplicate keys found
+
+    @retval  0           Success
+    @retval  >0          Error code
   */
   virtual int exec_bulk_update(uint *dup_key_found)
   {
     DBUG_ASSERT(FALSE);
     return HA_ERR_WRONG_COMMAND;
   }
-  /*
-    SYNOPSIS
+  /**
     Perform any needed clean-up, no outstanding updates are there at the
     moment.
-
-      end_bulk_update()
-    RETURN
-      Nothing
   */
   virtual void end_bulk_update() { return; }
-  /*
-    SYNOPSIS
+  /**
     Execute all outstanding deletes and close down the bulk delete.
 
-      end_bulk_delete()
-    RETURN
-    0             Success
-    >0            Error code
+    @retval 0             Success
+    @retval >0            Error code
   */
   virtual int end_bulk_delete()
   {
     DBUG_ASSERT(FALSE);
     return HA_ERR_WRONG_COMMAND;
   }
-  private:
+private:
   virtual int index_read(uchar * buf, const uchar * key, uint key_len,
                          enum ha_rkey_function find_flag)
    { return  HA_ERR_WRONG_COMMAND; }
-  public:
+public:
   /**
      @brief
      Positions an index cursor to the index specified in the handle. Fetches the
@@ -1315,7 +1297,7 @@ public:
   private:
   virtual int index_read_last(uchar * buf, const uchar * key, uint key_len)
    { return (my_errno=HA_ERR_WRONG_COMMAND); }
-  public:
+public:
   /**
      @brief
      The following functions works like index_read, but it find the last
@@ -1343,11 +1325,11 @@ public:
   virtual int ft_read(uchar *buf) { return HA_ERR_WRONG_COMMAND; }
   virtual int rnd_next(uchar *buf)=0;
   virtual int rnd_pos(uchar * buf, uchar *pos)=0;
-  /*
-    one has to use this method when to find
+  /**
+    One has to use this method when to find
     random position by record as the plain
     position() call doesn't work for some
-    handlers for random position
+    handlers for random position.
   */
   virtual int rnd_pos_by_record(uchar *record)
     {
@@ -1355,9 +1337,9 @@ public:
       return rnd_pos(record, ref);
     }
   virtual int read_first_row(uchar *buf, uint primary_key);
-  /*
+  /**
     The following function is only needed for tables that may be temporary
-    tables during joins
+    tables during joins.
   */
   virtual int restart_rnd_next(uchar *buf, uchar *pos)
     { return HA_ERR_WRONG_COMMAND; }
@@ -1374,13 +1356,13 @@ public:
   virtual int extra_opt(enum ha_extra_function operation, ulong cache_size)
   { return extra(operation); }
 
-  /*
-    Reset state of file to after 'open'
+  /**
+    Reset state of file to after 'open'.
     This function is called after every statement for all tables used
     by that statement.
   */
   virtual int reset() { return 0; }
-  /*
+  /**
     In an UPDATE or DELETE, if the row under the cursor was locked by another
     transaction, and the engine used an optimistic read of the last
     committed row value under the cursor, then the engine returns 1 from this
@@ -1393,7 +1375,7 @@ public:
     engine that the next read will be a locking re-read of the row.
   */
   virtual bool was_semi_consistent_read() { return 0; }
-  /*
+  /**
     Tell the engine whether it should avoid unnecessary lock waits.
     If yes, in an UPDATE or DELETE, if the row under the cursor was locked
     by another transaction, the engine may try an optimistic read of
@@ -1402,7 +1384,7 @@ public:
   virtual void try_semi_consistent_read(bool) {}
   virtual void unlock_row() {}
   virtual int start_stmt(THD *thd, thr_lock_type lock_type) {return 0;}
-  /*
+  /**
     This is called to delete all rows in a table
     If the handler don't support this, then this function will
     return HA_ERR_WRONG_COMMAND and MySQL will delete the rows one
@@ -1438,7 +1420,7 @@ public:
     next_insert_id= (prev_insert_id > 0) ? prev_insert_id :
       insert_id_for_cur_row;
   }
-  /*
+  /**
     Reset the auto-increment counter to the given value, i.e. the next row
     inserted will get the given value. This is called e.g. after TRUNCATE
     is emulated by doing a 'DELETE FROM t'. HA_ERR_WRONG_COMMAND is
@@ -1451,27 +1433,27 @@ public:
 protected:
   /* to be implemented in handlers */
 
-  /* admin commands - called from mysql_admin_table */
+  /** admin commands - called from mysql_admin_table */
   virtual int check(THD* thd, HA_CHECK_OPT* check_opt)
   { return HA_ADMIN_NOT_IMPLEMENTED; }
 
-  /*
-     in these two methods check_opt can be modified
+  /**
+     In these two methods check_opt can be modified
      to specify CHECK option to use to call check()
-     upon the table
+     upon the table.
   */
   virtual int check_for_upgrade(HA_CHECK_OPT *check_opt)
   { return 0; }
 public:
   int ha_check_for_upgrade(HA_CHECK_OPT *check_opt);
   int check_old_types();
-  /* to be actually called to get 'check()' functionality*/
+  /** to be actually called to get 'check()' functionality*/
   int ha_check(THD *thd, HA_CHECK_OPT *check_opt);
  
   virtual int backup(THD* thd, HA_CHECK_OPT* check_opt)
   { return HA_ADMIN_NOT_IMPLEMENTED; }
-  /*
-    restore assumes .frm file must exist, and that generate_table() has been
+  /**
+    Restore assumes .frm file must exist, and that generate_table() has been
     called; It will just copy the data file and run repair.
   */
   virtual int restore(THD* thd, HA_CHECK_OPT* check_opt)
@@ -1512,17 +1494,15 @@ public:
   virtual char *update_table_comment(const char * comment)
   { return (char*) comment;}
   virtual void append_create_info(String *packet) {}
-  /*
-    SYNOPSIS
-      is_fk_defined_on_table_or_index()
-      index            Index to check if foreign key uses it
-    RETURN VALUE
-       TRUE            Foreign key defined on table or index
-       FALSE           No foreign key defined
-    DESCRIPTION
+  /**
     If index == MAX_KEY then a check for table is made and if index <
     MAX_KEY then a check is made if the table has foreign keys and if
     a foreign key uses this index (and thus the index cannot be dropped).
+
+    @param  index            Index to check if foreign key uses it
+
+    @retval   TRUE            Foreign key defined on table or index
+    @retval   FALSE           No foreign key defined
   */
   virtual bool is_fk_defined_on_table_or_index(uint index)
   { return FALSE; }
@@ -1530,18 +1510,18 @@ public:
   { return(NULL);}  /* gets foreign key create string from InnoDB */
   virtual char* get_tablespace_name(THD *thd, char *name, uint name_len)
   { return(NULL);}  /* gets tablespace name from handler */
-  /* used in ALTER TABLE; 1 if changing storage engine is allowed */
+  /** used in ALTER TABLE; 1 if changing storage engine is allowed */
   virtual bool can_switch_engines() { return 1; }
-  /* used in REPLACE; is > 0 if table is referred by a FOREIGN KEY */
+  /** used in REPLACE; is > 0 if table is referred by a FOREIGN KEY */
   virtual int get_foreign_key_list(THD *thd, List<FOREIGN_KEY_INFO> *f_key_list)
   { return 0; }
   virtual uint referenced_by_foreign_key() { return 0;}
   virtual void init_table_handle_for_HANDLER()
   { return; }       /* prepare InnoDB for HANDLER */
   virtual void free_foreign_key_create_info(char* str) {}
-  /* The following can be called without an open handler */
+  /** The following can be called without an open handler */
   virtual const char *table_type() const =0;
-  /*
+  /**
     If frm_error() is called then we will use this to find out what file
     extentions exist for the storage engine. This is also used by the default
     rename_table and delete_table method in handler.cc.
@@ -1598,7 +1578,7 @@ public:
   virtual bool is_crashed() const  { return 0; }
   virtual bool auto_repair() const { return 0; }
 
-  /*
+  /**
     default rename_table() and delete_table() rename/delete files with a
     given name and extensions from bas_ext()
   */
@@ -1658,7 +1638,7 @@ public:
 				     THR_LOCK_DATA **to,
 				     enum thr_lock_type lock_type)=0;
 
-  /* Type of table for caching query */
+  /** Type of table for caching query */
   virtual uint8 table_cache_type() { return HA_CACHE_TBL_NONTRANSACT; }
 
 
@@ -1704,9 +1684,9 @@ public:
 
 
  /*
-  RETURN
-    true  Primary key (if there is one) is clustered key covering all fields
-    false otherwise
+   @retval TRUE   Primary key (if there is one) is clustered
+                  key covering all fields
+   @retval FALSE  otherwise
  */
  virtual bool primary_key_is_clustered() { return FALSE; }
  virtual int cmp_ref(const uchar *ref1, const uchar *ref2)
@@ -1718,19 +1698,18 @@ public:
    Condition pushdown to storage engines
  */
 
- /*
+ /**
    Push condition down to the table handler.
-   SYNOPSIS
-     cond_push()
-     cond   Condition to be pushed. The condition tree must not be            
+
+   @param  cond   Condition to be pushed. The condition tree must not be
                   modified by the by the caller.
 
-   RETURN
+   @return
      The 'remainder' condition that caller must use to filter out records.
      NULL means the handler will not return rows that do not match the
      passed condition.
 
-   NOTES
+   @note
    The pushed conditions form a stack (from which one can remove the
    last pushed condition using cond_pop).
    The table handler filters out rows using (pushed_cond1 AND pushed_cond2 
@@ -1742,18 +1721,17 @@ public:
    condition stack.
  */ 
  virtual const COND *cond_push(const COND *cond) { return cond; };
- /*
+ /**
    Pop the top condition from the condition stack of the handler instance.
-   SYNOPSIS
-     cond_pop()
-     Pops the top if condition stack, if stack is not empty
+
+   Pops the top if condition stack, if stack is not empty.
  */
  virtual void cond_pop() { return; };
  virtual bool check_if_incompatible_data(HA_CREATE_INFO *create_info,
 					 uint table_changes)
  { return COMPATIBLE_DATA_NO; }
 
- /* These are only called from sql_select for internal temporary tables */
+ /** These are only called from sql_select for internal temporary tables */
   virtual int write_row(uchar *buf __attribute__((unused)))
   {
     return HA_ERR_WRONG_COMMAND;
@@ -1769,7 +1747,7 @@ public:
   {
     return HA_ERR_WRONG_COMMAND;
   }
-  /*
+  /**
     use_hidden_primary_key() is called in case of an update/delete when
     (table_flags() and HA_PRIMARY_KEY_REQUIRED_FOR_DELETE) is defined
     but we don't have a primary key