Updated file to use doxygen commenting style.

1 files changed, 150 insertions, 56 deletions

diff --git a/storage/example/ha_example.h b/storage/example/ha_example.h
index 4e2de9be3d3..2d173368493 100644
--- a/storage/example/ha_example.h
+++ b/storage/example/ha_example.h
@@ -14,20 +14,31 @@
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/*
-  Please read ha_exmple.cc before reading this file.
-  Please keep in mind that the example storage engine implements all methods
-  that are required to be implemented. handler.h has a full list of methods
-  that you can implement.
+/** @file ha_example.h
+
+    @brief
+  The ha_example engine is a stubbed storage engine for example purposes only;
+  it does nothing at this point. Its purpose is to provide a source
+  code illustration of how to begin writing new storage engines; see also
+  /storage/example/ha_example.cc.
+
+    @note
+  Please read ha_example.cc before reading this file.
+  Reminder: The example storage engine implements all methods that are *required*
+  to be implemented. For a full list of all methods that you can implement, see
+  handler.h.
+
+   @see
+  /sql/handler.h and /storage/example/ha_example.cc
 */
 
 #ifdef USE_PRAGMA_INTERFACE
 #pragma interface			/* gcc class implementation */
 #endif
 
-/*
-  EXAMPLE_SHARE is a structure that will be shared amoung all open handlers
-  The example implements the minimum of what you will probably need.
+/** @brief
+  EXAMPLE_SHARE is a structure that will be shared among all open handlers.
+  This example implements the minimum of what you will probably need.
 */
 typedef struct st_example_share {
   char *table_name;
@@ -36,117 +47,200 @@ typedef struct st_example_share {
   THR_LOCK lock;
 } EXAMPLE_SHARE;
 
-/*
+/** @brief
   Class definition for the storage engine
 */
 class ha_example: public handler
 {
-  THR_LOCK_DATA lock;      /* MySQL lock */
-  EXAMPLE_SHARE *share;    /* Shared lock info */
+  THR_LOCK_DATA lock;      ///< MySQL lock
+  EXAMPLE_SHARE *share;    ///< Shared lock info
 
 public:
   ha_example(handlerton *hton, TABLE_SHARE *table_arg);
   ~ha_example()
   {
   }
-  /* The name that will be used for display purposes */
+
+  /** @brief
+    The name that will be used for display purposes.
+   */
   const char *table_type() const { return "EXAMPLE"; }
-  /*
-    The name of the index type that will be used for display
-    don't implement this method unless you really have indexes
+
+  /** @brief
+    The name of the index type that will be used for display.
+    Don't implement this method unless you really have indexes.
    */
   const char *index_type(uint inx) { return "HASH"; }
+
+  /** @brief
+    The file extensions.
+   */
   const char **bas_ext() const;
-  /*
-    This is a list of flags that says what the storage engine
-    implements. The current table flags are documented in
-    handler.h
+
+  /** @brief
+    This is a list of flags that indicate what functionality the storage engine
+    implements. The current table flags are documented in handler.h
   */
   ulonglong table_flags() const
   {
     return 0;
   }
-  /*
-    This is a bitmap of flags that says how the storage engine
+
+  /** @brief
+    This is a bitmap of flags that indicates how the storage engine
     implements indexes. The current index flags are documented in
-    handler.h. If you do not implement indexes, just return zero
-    here.
+    handler.h. If you do not implement indexes, just return zero here.
 
-    part is the key part to check. First key part is 0
-    If all_parts it's set, MySQL want to know the flags for the combined
-    index up to and including 'part'.
+      @details
+    part is the key part to check. First key part is 0.
+    If all_parts is set, MySQL wants to know the flags for the combined
+    index, up to and including 'part'.
   */
   ulong index_flags(uint inx, uint part, bool all_parts) const
   {
     return 0;
   }
-  /*
-    unireg.cc will call the following to make sure that the storage engine can
-    handle the data it is about to send.
-
-    Return *real* limits of your storage engine here. MySQL will do
-    min(your_limits, MySQL_limits) automatically
 
-    There is no need to implement ..._key_... methods if you don't suport
-    indexes.
-  */
+  /** @brief
+    unireg.cc will call max_supported_record_length(), max_supported_keys(),
+    max_supported_key_parts(), uint max_supported_key_length()
+    to make sure that the storage engine can handle the data it is about to
+    send. Return *real* limits of your storage engine here; MySQL will do
+    min(your_limits, MySQL_limits) automatically.
+   */
   uint max_supported_record_length() const { return HA_MAX_REC_LENGTH; }
+
+  /** @brief
+    unireg.cc will call this to make sure that the storage engine can handle
+    the data it is about to send. Return *real* limits of your storage engine
+    here; MySQL will do min(your_limits, MySQL_limits) automatically.
+
+      @details
+    There is no need to implement ..._key_... methods if your engine doesn't
+    support indexes.
+   */
   uint max_supported_keys()          const { return 0; }
+
+  /** @brief
+    unireg.cc will call this to make sure that the storage engine can handle
+    the data it is about to send. Return *real* limits of your storage engine
+    here; MySQL will do min(your_limits, MySQL_limits) automatically.
+
+      @details
+    There is no need to implement ..._key_... methods if your engine doesn't
+    support indexes.
+   */
   uint max_supported_key_parts()     const { return 0; }
+
+  /** @brief
+    unireg.cc will call this to make sure that the storage engine can handle
+    the data it is about to send. Return *real* limits of your storage engine
+    here; MySQL will do min(your_limits, MySQL_limits) automatically.
+
+      @details
+    There is no need to implement ..._key_... methods if your engine doesn't
+    support indexes.
+   */
   uint max_supported_key_length()    const { return 0; }
-  /*
+
+  /** @brief
     Called in test_quick_select to determine if indexes should be used.
   */
   virtual double scan_time() { return (double) (stats.records+stats.deleted) / 20.0+10; }
-  /*
-    The next method will never be called if you do not implement indexes.
+
+  /** @brief
+    This method will never be called if you do not implement indexes.
   */
   virtual double read_time(ha_rows rows) { return (double) rows /  20.0+1; }
 
   /*
-    Everything below are methods that we implment in ha_example.cc.
+    Everything below are methods that we implement in ha_example.cc.
 
     Most of these methods are not obligatory, skip them and
     MySQL will treat them as not implemented
   */
+  /** @brief
+    We implement this in ha_example.cc; it's a required method.
+  */
   int open(const char *name, int mode, uint test_if_locked);    // required
+
+  /** @brief
+    We implement this in ha_example.cc; it's a required method.
+  */
   int close(void);                                              // required
 
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int write_row(byte * buf);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int update_row(const byte * old_data, byte * new_data);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int delete_row(const byte * buf);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int index_read(byte * buf, const byte * key,
                  uint key_len, enum ha_rkey_function find_flag);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int index_next(byte * buf);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int index_prev(byte * buf);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int index_first(byte * buf);
+
+  /** @brief
+    We implement this in ha_example.cc. It's not an obligatory method;
+    skip it and and MySQL will treat it as not implemented.
+  */
   int index_last(byte * buf);
-  /*
-    unlike index_init(), 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 if rnd_init allocates the cursor, second call should
-    position it to the start of the table, no need to deallocate
-    and allocate it again
+
+  /** @brief
+    Unlike index_init(), rnd_init() can be called two consecutive times
+    without rnd_end() in between (it only makes sense if scan=1). In this
+    case, the second call should prepare for the new table scan (e.g if
+    rnd_init() allocates the cursor, the second call should position the
+    cursor to the start of the table; no need to deallocate and allocate
+    it again. This is a required method.
   */
   int rnd_init(bool scan);                                      //required
   int rnd_end();
-  int rnd_next(byte *buf);                                      //required
-  int rnd_pos(byte * buf, byte *pos);                           //required
-  void position(const byte *record);                            //required
-  int info(uint);                                              //required
-
+  int rnd_next(byte *buf);                                      ///< required
+  int rnd_pos(byte * buf, byte *pos);                           ///< required
+  void position(const byte *record);                            ///< required
+  int info(uint);                                               ///< required
   int extra(enum ha_extra_function operation);
-  int external_lock(THD *thd, int lock_type);                   //required
+  int external_lock(THD *thd, int lock_type);                   ///< required
   int delete_all_rows(void);
   ha_rows records_in_range(uint inx, key_range *min_key,
                            key_range *max_key);
   int delete_table(const char *from);
   int rename_table(const char * from, const char * to);
   int create(const char *name, TABLE *form,
-             HA_CREATE_INFO *create_info);                      //required
+             HA_CREATE_INFO *create_info);                      ///< required
 
   THR_LOCK_DATA **store_lock(THD *thd, THR_LOCK_DATA **to,
-                             enum thr_lock_type lock_type);     //required
-};
-
+                             enum thr_lock_type lock_type);     ///< required