Doxygenized comments.

sql/sql_base.cc

@@ -1817,7 +1817,7 @@ static void relink_unused(TABLE *table)
 
 
 /**
-    @brief  Remove all instances of table from thread's open list and
+    Remove all instances of table from thread's open list and
     table cache.
 
     @param  thd     Thread context
@@ -1867,7 +1867,7 @@ void unlink_open_table(THD *thd, TABLE *find, bool unlock)
 
 
 /**
-    @brief Auxiliary routine which closes and drops open table.
+    Auxiliary routine which closes and drops open table.
 
     @param  thd         Thread handle
     @param  table       TABLE object for table to be dropped
@@ -2039,7 +2039,7 @@ bool reopen_name_locked_table(THD* thd, TABLE_LIST* table_list, bool link_in)
 
 
 /**
-    @brief Create and insert into table cache placeholder for table
+    Create and insert into table cache placeholder for table
     which will prevent its opening (or creation) (a.k.a lock
     table name).
 
@@ -2090,7 +2090,7 @@ TABLE *table_cache_insert_placeholder(THD *thd, const char *key,
 
 
 /**
-    @brief Obtain an exclusive name lock on the table if it is not cached
+    Obtain an exclusive name lock on the table if it is not cached
     in the table cache.
 
     @param      thd         Thread context
@@ -2142,7 +2142,7 @@ bool lock_table_name_if_not_cached(THD *thd, const char *db,
 
 
 /**
-    @brief Check that table exists in table definition cache, on disk
+    Check that table exists in table definition cache, on disk
     or in some storage engine.
 
     @param       thd     Thread context
@@ -2815,7 +2815,7 @@ bool reopen_table(TABLE *table)
 
 
 /**
-    @brief Close all instances of a table open by this thread and replace
+    Close all instances of a table open by this thread and replace
     them with exclusive name-locks.
 
     @param thd        Thread context
@@ -2867,7 +2867,7 @@ void close_data_files_and_morph_locks(THD *thd, const char *db,
 
 
 /**
-    @brief Reopen all tables with closed data files.
+    Reopen all tables with closed data files.
 
     @param thd         Thread context
     @param get_locks   Should we get locks after reopening tables ?
@@ -2957,7 +2957,7 @@ bool reopen_tables(THD *thd,bool get_locks,bool in_refresh)
 
 
 /**
-    @brief Close handlers for tables in list, but leave the TABLE structure
+    Close handlers for tables in list, but leave the TABLE structure
     intact so that we can re-open these quickly.
 
     @param thd           Thread context

sql/sql_cache.cc

@@ -1524,7 +1524,7 @@ void Query_cache::invalidate(THD *thd, const char *key, uint32  key_length,
 
 
 /**
-  @brief Synchronize the thread with any flushing operations.
+  Synchronize the thread with any flushing operations.
 
   This helper function is called whenever a thread needs to operate on the
   query cache structure (example: during invalidation). If a table flush is in
@@ -1565,7 +1565,7 @@ void Query_cache::wait_while_table_flush_is_in_progress(bool *interrupt)
 
 
 /**
-   @brief Remove all cached queries that uses the given database
+   Remove all cached queries that uses the given database.
 */
 
 void Query_cache::invalidate(char *db)
@@ -1675,7 +1675,7 @@ void Query_cache::flush()
 
 
 /**
-  @brief Rearrange the memory blocks and join result in cache in 1 block (if
+  Rearrange the memory blocks and join result in cache in 1 block (if
   result length > join_limit)
 
   @param[in] join_limit If the minimum length of a result block to be joined.
@@ -1946,7 +1946,7 @@ void Query_cache::make_disabled()
 
 /**
   @class Query_cache
-  @brief Free all resources allocated by the cache.
+  Free all resources allocated by the cache.
 
   This function frees all resources allocated by the cache.  You
   have to call init_cache() before using the cache again. This function
@@ -1970,7 +1970,7 @@ void Query_cache::free_cache()
 
 
 /**
-  @brief Flush the cache.
+  Flush the cache.
 
   This function will flush cache contents.  It assumes we have
   'structure_guard_mutex' locked. The function sets the m_cache_status flag and
@@ -2516,7 +2516,7 @@ Query_cache::invalidate_table_internal(THD *thd, uchar *key, uint32 key_length)
 }
 
 /**
-  @brief Invalidate a linked list of query cache blocks.
+  Invalidate a linked list of query cache blocks.
 
   Each block tries to aquire a block level lock before
   free_query is a called. This function will in turn affect
@@ -2684,7 +2684,7 @@ my_bool Query_cache::register_all_tables(Query_cache_block *block,
 
 
 /**
-  @brief Insert used table name into the cache.
+  Insert used table name into the cache.
 
   @return Error status
     @retval FALSE On error
@@ -3413,7 +3413,7 @@ my_bool Query_cache::ask_handler_allowance(THD *thd,
 
 
 /**
-  @brief Rearrange all memory blocks so that free memory joins at the
+  Rearrange all memory blocks so that free memory joins at the
   'bottom' of the allocated memory block containing all cache data.
   @see Query_cache::pack(ulong join_limit, uint iteration_limit)
 */
@@ -4028,7 +4028,7 @@ void Query_cache::tables_dump()
 
 
 /**
-  @brief Checks integrity of the various linked lists
+  Checks integrity of the various linked lists
 
   @return Error status code
     @retval FALSE Query cache is operational.

sql/sql_class.cc

@@ -934,7 +934,7 @@ void THD::cleanup_after_query()
 
 
 /**
-  Create a LEX_STRING in this connection
+  Create a LEX_STRING in this connection.
 
   @param lex_str  pointer to LEX_STRING object to be initialized
   @param str      initializer to be copied into lex_str

sql/sql_cursor.cc

@@ -24,9 +24,9 @@
   Declarations.
 ****************************************************************************/
 
-/*
+/**
   Sensitive_cursor -- a sensitive non-materialized server side
-  cursor An instance of this class cursor has its own runtime
+  cursor.  An instance of this class cursor has its own runtime
   state -- list of used items and memory root for runtime memory,
   open and locked tables, change list for the changes of the
   parsed tree. This state is freed when the cursor is closed.
@@ -69,7 +69,7 @@ class Sensitive_cursor: public Server_side_cursor
 };
 
 
-/*
+/**
   Materialized_cursor -- an insensitive materialized server-side
   cursor. The result set of this cursor is saved in a temporary
   table at open. The cursor itself is simply an interface for the
@@ -96,7 +96,7 @@ class Materialized_cursor: public Server_side_cursor
 };
 
 
-/*
+/**
   Select_materialize -- a mediator between a cursor query and the
   protocol. In case we were not able to open a non-materialzed
   cursor, it creates an internal temporary HEAP table, and insert
@@ -107,7 +107,7 @@ class Materialized_cursor: public Server_side_cursor
 
 class Select_materialize: public select_union
 {
-  select_result *result; /* the result object of the caller (PS or SP) */
+  select_result *result; /**< the result object of the caller (PS or SP) */
 public:
   Select_materialize(select_result *result_arg) :result(result_arg) {}
   virtual bool send_fields(List<Item> &list, uint flags);
@@ -116,21 +116,20 @@ class Select_materialize: public select_union
 
 /**************************************************************************/
 
-/*
+/**
   Attempt to open a materialized or non-materialized cursor.
 
-  SYNOPSIS
-    mysql_open_cursor()
-      thd                thread handle
-      flags   [in]       create a materialized cursor or not
-      result  [in]       result class of the caller used as a destination
+  @param      thd           thread handle
+  @param[in]  flags         create a materialized cursor or not
+  @param[in]  result        result class of the caller used as a destination
                             for the rows fetched from the cursor
-      pcursor [out]      a pointer to store a pointer to cursor in
+  @param[out] pcursor       a pointer to store a pointer to cursor in
 
-  RETURN VALUE
+  @retval
     0                 the query has been successfully executed; in this
     case pcursor may or may not contain
     a pointer to an open cursor.
+  @retval
     non-zero          an error, 'pcursor' has been left intact.
 */
 
@@ -279,6 +278,14 @@ Sensitive_cursor::Sensitive_cursor(THD *thd, select_result *result_arg)
 }
 
 
+/**
+  Save THD state into cursor.
+
+  @todo
+    - XXX: thd->locked_tables is not changed.
+    -  What problems can we have with it if cursor is open?
+    - TODO: must be fixed because of the prelocked mode.
+*/
 void
 Sensitive_cursor::post_open(THD *thd)
 {
@@ -334,6 +341,10 @@ Sensitive_cursor::post_open(THD *thd)
 }
 
 
+/**
+  bzero cursor state in THD.
+*/
+
 void
 Sensitive_cursor::reset_thd(THD *thd)
 {
@@ -393,20 +404,13 @@ Sensitive_cursor::open(JOIN *join_arg)
 }
 
 
-/*
-  SYNOPSIS
-    Sensitive_cursor::fetch()
-      num_rows           fetch up to this number of rows (maybe less)
-
-  DESCRIPTION
-    Fetch next num_rows rows from the cursor and send them to the client
+/**
+  Fetch next num_rows rows from the cursor and send them to the client.
 
   Precondition:
-    Sensitive_cursor is open
+  - Sensitive_cursor is open
 
-  RETURN VALUES:
-    none, this function will send OK to the clinet or set an error
-    message in THD
+  @param num_rows           fetch up to this number of rows (maybe less)
 */
 
 void
@@ -478,6 +482,11 @@ Sensitive_cursor::fetch(ulong num_rows)
 }
 
 
+/**
+  @todo
+  Another hack: we need to set THD state as if in a fetch to be
+  able to call stmt close.
+*/
 void
 Sensitive_cursor::close()
 {
@@ -579,10 +588,9 @@ int Materialized_cursor::open(JOIN *join __attribute__((unused)))
 }
 
 
-/*
+/**
   Fetch up to the given number of rows from a materialized cursor.
 
-  DESCRIPTION
     Precondition: the cursor is open.
 
     If the cursor points after the last row, the fetch will automatically
@@ -590,10 +598,6 @@ int Materialized_cursor::open(JOIN *join __attribute__((unused)))
     with SERVER_STATUS_LAST_ROW_SENT). This is an extra round trip
     and probably should be improved to return
     SERVER_STATUS_LAST_ROW_SENT along with the last row.
-
-  RETURN VALUE
-    none, in case of success the row is sent to the client, otherwise
-    an error message is set in THD
 */
 
 void Materialized_cursor::fetch(ulong num_rows)

sql/sql_update.cc

@@ -84,7 +84,7 @@ static bool check_fields(THD *thd, List<Item> &items)
 
 
 /**
-  @brief Re-read record if more columns are needed for error message.
+  Re-read record if more columns are needed for error message.
 
   If we got a duplicate key error, we want to write an error
   message containing the value of the duplicate key. If we do not have

sql/sql_view.cc

@@ -206,7 +206,7 @@ fill_defined_view_parts (THD *thd, TABLE_LIST *view)
 
 
 /**
-  @brief Creating/altering VIEW procedure
+  Creating/altering VIEW procedure
 
   @param thd thread handler
   @param views views to create