branches/innodb+: Merge revisions 5091:5143 from branches/zip:

  ------------------------------------------------------------------------
  r5092 | marko | 2009-05-25 09:54:17 +0300 (Mon, 25 May 2009) | 1 line

  branches/zip: Adjust some function comments after r5091.
  ------------------------------------------------------------------------
  r5100 | marko | 2009-05-25 12:09:45 +0300 (Mon, 25 May 2009) | 1 line

  branches/zip: Split some long lines that were introduced in r5091.
  ------------------------------------------------------------------------
  r5101 | marko | 2009-05-25 12:42:47 +0300 (Mon, 25 May 2009) | 2 lines

  branches/zip: Introduce the macro TEMP_INDEX_PREFIX_STR.
  This is to avoid triggering an error in Doxygen.
  ------------------------------------------------------------------------
  r5102 | marko | 2009-05-25 13:47:14 +0300 (Mon, 25 May 2009) | 1 line

  branches/zip: Add missing file comments.
  ------------------------------------------------------------------------
  r5103 | marko | 2009-05-25 13:52:29 +0300 (Mon, 25 May 2009) | 10 lines

  branches/zip: Add @file comments, and convert decorative
  /*********************************
  comments to Doxygen /** style like this:
  /*****************************//**

  This conversion was performed by the following command:

  perl -i -e 'while(<ARGV>){if (m|^/\*{30}\**$|) {
  s|\*{4}$|//**| if ++$com>1; $_ .= "\@file $ARGV\n" if $com==2}
  print; if(eof){$.=0;undef $com}}' */*[ch] include/univ.i
  ------------------------------------------------------------------------
  r5104 | marko | 2009-05-25 14:39:07 +0300 (Mon, 25 May 2009) | 2 lines

  branches/zip: Revert ut0auxconf_* to r5102,
  that is, make Doxygen ignore these test programs.
  ------------------------------------------------------------------------
  r5105 | marko | 2009-05-25 14:52:20 +0300 (Mon, 25 May 2009) | 2 lines

  branches/zip: Enclose some #error checks inside #ifndef DOXYGEN
  to prevent bogus Doxygen errors.
  ------------------------------------------------------------------------
  r5106 | marko | 2009-05-25 16:09:24 +0300 (Mon, 25 May 2009) | 2 lines

  branches/zip: Add some Doxygen comments, mainly to structs, typedefs,
  macros and global variables.  Many more to go.
  ------------------------------------------------------------------------
  r5108 | marko | 2009-05-26 00:32:35 +0300 (Tue, 26 May 2009) | 2 lines

  branches/zip: lexyy.c: Remove the inadvertently added @file directive.
  There is nothing for Doxygen to see in this file, move along.
  ------------------------------------------------------------------------
  r5125 | marko | 2009-05-26 16:28:49 +0300 (Tue, 26 May 2009) | 3 lines

  branches/zip: Add some Doxygen comments for many structs, typedefs,
  #defines and global variables.  Many are still missing.
  ------------------------------------------------------------------------
  r5134 | marko | 2009-05-27 09:08:43 +0300 (Wed, 27 May 2009) | 1 line

  branches/zip: Add some Doxygen @return comments.
  ------------------------------------------------------------------------
  r5139 | marko | 2009-05-27 10:01:40 +0300 (Wed, 27 May 2009) | 1 line

  branches/zip: Add Doxyfile.
  ------------------------------------------------------------------------
  r5143 | marko | 2009-05-27 10:57:25 +0300 (Wed, 27 May 2009) | 3 lines

  branches/zip: buf0buf.h, Doxyfile: Fix the Doxygen translation.
  @defgroup is for source code modules, not for field groups.
  Tell Doxygen to expand the UT_LIST declarations.
  ------------------------------------------------------------------------

ChangeLog

+2009-05-27	The InnoDB Team
+
+	* Doxyfile:
+	Allow the extraction of documentation from the code base with the
+	Doxygen tool.  Convert and add many (but not yet all) comments to
+	Doxygen format.
+
 2009-05-19	The InnoDB Team
 
 	* btr/btr0btr.c, btr/btr0cur.c, lock/lock0lock.c,

btr/btr0pcur.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file btr/btr0pcur.c
 The index tree persistent cursor
 
 Created 2/23/1996 Heikki Tuuri
@@ -32,7 +33,7 @@ Created 2/23/1996 Heikki Tuuri
 #include "rem0cmp.h"
 #include "trx0trx.h"
 
-/******************************************************************
+/**************************************************************//**
 Allocates memory for a persistent cursor object and initializes the cursor.
 @return	own: persistent cursor */
 UNIV_INTERN
@@ -50,7 +51,7 @@ btr_pcur_create_for_mysql(void)
 	return(pcur);
 }
 
-/******************************************************************
+/**************************************************************//**
 Frees the memory for a persistent cursor object. */
 UNIV_INTERN
 void
@@ -76,7 +77,7 @@ btr_pcur_free_for_mysql(
 	mem_free(cursor);
 }
 
-/******************************************************************
+/**************************************************************//**
 The position of the cursor is stored by taking an initial segment of the
 record the cursor is positioned on, before, or after, and copying it to the
 cursor data structure, or just setting a flag if the cursor id before the
@@ -157,7 +158,7 @@ btr_pcur_store_position(
 	cursor->modify_clock = buf_block_get_modify_clock(block);
 }
 
-/******************************************************************
+/**************************************************************//**
 Copies the stored position of a pcur to another pcur. */
 UNIV_INTERN
 void
@@ -187,7 +188,7 @@ btr_pcur_copy_stored_position(
 	pcur_receive->old_n_fields = pcur_donate->old_n_fields;
 }
 
-/******************************************************************
+/**************************************************************//**
 Restores the stored position of a persistent cursor bufferfixing the page and
 obtaining the specified latches. If the cursor position was saved when the
 (1) cursor was positioned on a user record: this function restores the position
@@ -199,7 +200,9 @@ infimum;
 GREATER than the user record which was the predecessor of the supremum.
 (4) cursor was positioned before the first or after the last in an empty tree:
 restores to before first or after the last in the tree.
-@return	TRUE if the cursor position was stored when it was on a user record and it can be restored on a user record whose ordering fields are identical to the ones of the original user record */
+@return TRUE if the cursor position was stored when it was on a user
+record and it can be restored on a user record whose ordering fields
+are identical to the ones of the original user record */
 UNIV_INTERN
 ibool
 btr_pcur_restore_position(
@@ -347,7 +350,7 @@ btr_pcur_restore_position(
 	return(FALSE);
 }
 
-/******************************************************************
+/**************************************************************//**
 If the latch mode of the cursor is BTR_LEAF_SEARCH or BTR_LEAF_MODIFY,
 releases the page latch and bufferfix reserved by the cursor.
 NOTE! In the case of BTR_LEAF_MODIFY, there should not exist changes
@@ -374,7 +377,7 @@ btr_pcur_release_leaf(
 	cursor->pos_state = BTR_PCUR_WAS_POSITIONED;
 }
 
-/*************************************************************
+/*********************************************************//**
 Moves the persistent cursor to the first record on the next page. Releases the
 latch on the current page, and bufferunfixes it. Note that there must not be
 modifications on the current page, as then the x-latch can be released only in
@@ -425,7 +428,7 @@ btr_pcur_move_to_next_page(
 	page_check_dir(next_page);
 }
 
-/*************************************************************
+/*********************************************************//**
 Moves the persistent cursor backward if it is on the first record of the page.
 Commits mtr. Note that to prevent a possible deadlock, the operation
 first stores the position of the cursor, commits mtr, acquires the necessary
@@ -507,7 +510,7 @@ btr_pcur_move_backward_from_page(
 	cursor->old_stored = BTR_PCUR_OLD_NOT_STORED;
 }
 
-/*************************************************************
+/*********************************************************//**
 Moves the persistent cursor to the previous record in the tree. If no records
 are left, the cursor stays 'before first in tree'.
 @return	TRUE if the cursor was not before first in tree */
@@ -541,7 +544,7 @@ btr_pcur_move_to_prev(
 	return(TRUE);
 }
 
-/******************************************************************
+/**************************************************************//**
 If mode is PAGE_CUR_G or PAGE_CUR_GE, opens a persistent cursor on the first
 user record satisfying the search condition, in the case PAGE_CUR_L or
 PAGE_CUR_LE, on the last user record. If no such user record exists, then

buf/buf0buddy.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file buf/buf0buddy.c
 Binary buddy allocator for compressed pages
 
 Created December 2006 by Marko Makela
@@ -44,7 +45,7 @@ static ulint buf_buddy_n_frames;
 Protected by buf_pool_mutex. */
 UNIV_INTERN buf_buddy_stat_t buf_buddy_stat[BUF_BUDDY_SIZES + 1];
 
-/**************************************************************************
+/**********************************************************************//**
 Get the offset of the buddy of a compressed page frame.
 @return	the buddy relative of page */
 UNIV_INLINE
@@ -66,7 +67,7 @@ buf_buddy_get(
 	}
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Add a block to the head of the appropriate buddy free list. */
 UNIV_INLINE
 void
@@ -92,7 +93,7 @@ buf_buddy_add_to_free(
 #endif /* UNIV_DEBUG_VALGRIND */
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Remove a block from the appropriate buddy free list. */
 UNIV_INLINE
 void
@@ -122,7 +123,7 @@ buf_buddy_remove_from_free(
 #endif /* UNIV_DEBUG_VALGRIND */
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Try to allocate a block from buf_pool->zip_free[].
 @return	allocated block, or NULL if buf_pool->zip_free[] was empty */
 static
@@ -175,7 +176,7 @@ buf_buddy_alloc_zip(
 	return(bpage);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Deallocate a buffer frame of UNIV_PAGE_SIZE. */
 static
 void
@@ -214,7 +215,7 @@ buf_buddy_block_free(
 	ut_d(buf_buddy_n_frames--);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Allocate a buffer block to the buddy allocator. */
 static
 void
@@ -240,7 +241,7 @@ buf_buddy_block_register(
 	ut_d(buf_buddy_n_frames++);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Allocate a block from a bigger object.
 @return	allocated block */
 static
@@ -280,7 +281,7 @@ buf_buddy_alloc_from(
 	return(buf);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Allocate a block.  The thread calling this function must hold
 buf_pool_mutex and must not hold buf_pool_zip_mutex or any block->mutex.
 The buf_pool_mutex may only be released and reacquired if lru != NULL.
@@ -340,7 +341,7 @@ buf_buddy_alloc_low(
 	return(block);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Try to relocate the control block of a compressed page.
 @return	TRUE if relocated */
 static
@@ -396,7 +397,7 @@ buf_buddy_relocate_block(
 	return(TRUE);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Try to relocate a block.
 @return	TRUE if relocated */
 static
@@ -504,7 +505,7 @@ buf_buddy_relocate(
 	return(FALSE);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Deallocate a block. */
 UNIV_INTERN
 void

buf/buf0flu.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file buf/buf0flu.c
 The database buffer buf_pool flush algorithm
 
 Created 11/11/1995 Heikki Tuuri
@@ -44,7 +45,7 @@ Created 11/11/1995 Heikki Tuuri
 #include "trx0sys.h"
 
 #if defined UNIV_DEBUG || defined UNIV_BUF_DEBUG
-/**********************************************************************
+/******************************************************************//**
 Validates the flush list.
 @return	TRUE if ok */
 static
@@ -53,7 +54,7 @@ buf_flush_validate_low(void);
 /*========================*/
 #endif /* UNIV_DEBUG || UNIV_BUF_DEBUG */
 
-/**********************************************************************
+/******************************************************************//**
 Insert a block in the flush_rbt and returns a pointer to its
 predecessor or NULL if no predecessor. The ordering is maintained
 on the basis of the <oldest_modification, space, offset> key.
@@ -85,7 +86,7 @@ buf_flush_insert_in_flush_rbt(
 	return(prev);
 }
 
-/*************************************************************
+/*********************************************************//**
 Delete a bpage from the flush_rbt. */
 static
 void
@@ -101,7 +102,7 @@ buf_flush_delete_from_flush_rbt(
 	ut_ad(ret);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Compare two modified blocks in the buffer pool. The key for comparison
 is:
 key = <oldest_modification, space, offset>
@@ -149,7 +150,7 @@ buf_flush_block_cmp(
 	return(ret ? ret : (int)(b2->offset - b1->offset));
 }
 
-/************************************************************************
+/********************************************************************//**
 Initialize the red-black tree to speed up insertions into the flush_list
 during recovery process. Should be called at the start of recovery
 process before any page has been read/written. */
@@ -166,7 +167,7 @@ buf_flush_init_flush_rbt(void)
 	buf_pool_mutex_exit();
 }
 
-/************************************************************************
+/********************************************************************//**
 Frees up the red-black tree. */
 UNIV_INTERN
 void
@@ -185,7 +186,7 @@ buf_flush_free_flush_rbt(void)
 	buf_pool_mutex_exit();
 }
 
-/************************************************************************
+/********************************************************************//**
 Inserts a modified block into the flush list. */
 UNIV_INTERN
 void
@@ -218,7 +219,7 @@ buf_flush_insert_into_flush_list(
 #endif /* UNIV_DEBUG || UNIV_BUF_DEBUG */
 }
 
-/************************************************************************
+/********************************************************************//**
 Inserts a modified block into the flush list in the right sorted position.
 This function is used by recovery, because there the modifications do not
 necessarily come in the order of lsn's. */
@@ -276,7 +277,7 @@ buf_flush_insert_sorted_into_flush_list(
 #endif /* UNIV_DEBUG || UNIV_BUF_DEBUG */
 }
 
-/************************************************************************
+/********************************************************************//**
 Returns TRUE if the file page block is immediately suitable for replacement,
 i.e., the transition FILE_PAGE => NOT_USED allowed.
 @return	TRUE if can replace immediately */
@@ -309,7 +310,7 @@ buf_flush_ready_for_replace(
 	return(FALSE);
 }
 
-/************************************************************************
+/********************************************************************//**
 Returns TRUE if the block is modified and ready for flushing.
 @return	TRUE if can flush immediately */
 UNIV_INLINE
@@ -346,7 +347,7 @@ buf_flush_ready_for_flush(
 	return(FALSE);
 }
 
-/************************************************************************
+/********************************************************************//**
 Remove a block from the flush list of modified blocks. */
 UNIV_INTERN
 void
@@ -393,7 +394,7 @@ buf_flush_remove(
 			      ut_ad(ut_list_node_313->in_flush_list)));
 }
 
-/***********************************************************************
+/*******************************************************************//**
 Relocates a buffer control block on the flush_list.
 Note that it is assumed that the contents of bpage has already been
 copied to dpage. */
@@ -450,7 +451,7 @@ buf_flush_relocate_on_flush_list(
 #endif /* UNIV_DEBUG || UNIV_BUF_DEBUG */
 }
 
-/************************************************************************
+/********************************************************************//**
 Updates the flush system data structures when a write is completed. */
 UNIV_INTERN
 void
@@ -488,7 +489,7 @@ buf_flush_write_complete(
 	}
 }
 
-/************************************************************************
+/********************************************************************//**
 Flushes possible buffered writes from the doublewrite memory buffer to disk,
 and also wakes up the aio thread if simulated aio is used. It is very
 important to call this function after a batch of writes has been posted,
@@ -735,7 +736,7 @@ buf_flush_buffered_writes(void)
 	mutex_exit(&(trx_doublewrite->mutex));
 }
 
-/************************************************************************
+/********************************************************************//**
 Posts a buffer page for writing. If the doublewrite memory buffer is
 full, calls buf_flush_buffered_writes and waits for for free space to
 appear. */
@@ -795,7 +796,7 @@ buf_flush_post_to_doublewrite_buf(
 }
 #endif /* !UNIV_HOTBACKUP */
 
-/************************************************************************
+/********************************************************************//**
 Initializes a page for writing to the tablespace. */
 UNIV_INTERN
 void
@@ -874,7 +875,7 @@ buf_flush_init_for_writing(
 }
 
 #ifndef UNIV_HOTBACKUP
-/************************************************************************
+/********************************************************************//**
 Does an asynchronous write of a buffer page. NOTE: in simulated aio and
 also when the doublewrite buffer is used, we must call
 buf_flush_buffered_writes after we have posted a batch of writes! */
@@ -962,7 +963,7 @@ buf_flush_write_block_low(
 	}
 }
 
-/************************************************************************
+/********************************************************************//**
 Writes a flushable page asynchronously from the buffer pool to a file.
 NOTE: in simulated aio we must call
 os_aio_simulated_wake_handler_threads after we have posted a batch of
@@ -1076,7 +1077,7 @@ buf_flush_page(
 	buf_flush_write_block_low(bpage);
 }
 
-/***************************************************************
+/***********************************************************//**
 Flushes to disk all flushable pages within the flush area.
 @return	number of pages flushed */
 static
@@ -1167,13 +1168,14 @@ buf_flush_try_neighbors(
 	return(count);
 }
 
-/***********************************************************************
+/*******************************************************************//**
 This utility flushes dirty blocks from the end of the LRU list or flush_list.
 NOTE 1: in the case of an LRU flush the calling thread may own latches to
 pages: to avoid deadlocks, this function must be written so that it cannot
 end up waiting for these latches! NOTE 2: in the case of a flush list flush,
 the calling thread is not allowed to own any latches on pages!
-@return	number of blocks for which the write request was queued; ULINT_UNDEFINED if there was a flush of the same type already running */
+@return number of blocks for which the write request was queued;
+ULINT_UNDEFINED if there was a flush of the same type already running */
 UNIV_INTERN
 ulint
 buf_flush_batch(
@@ -1322,7 +1324,7 @@ buf_flush_batch(
 	return(page_count);
 }
 
-/**********************************************************************
+/******************************************************************//**
 Waits until a flush batch of the given type ends */
 UNIV_INTERN
 void
@@ -1335,11 +1337,12 @@ buf_flush_wait_batch_end(
 	os_event_wait(buf_pool->no_flush[type]);
 }
 
-/**********************************************************************
+/******************************************************************//**
 Gives a recommendation of how many blocks should be flushed to establish
 a big enough margin of replaceable blocks near the end of the LRU list
 and in the free list.
-@return	number of blocks which should be flushed from the end of the LRU list */
+@return number of blocks which should be flushed from the end of the
+LRU list */
 static
 ulint
 buf_flush_LRU_recommendation(void)
@@ -1386,7 +1389,7 @@ buf_flush_LRU_recommendation(void)
 	       - n_replaceable);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Flushes pages from the end of the LRU list if there is too small a margin
 of replaceable pages there or in the free list. VERY IMPORTANT: this function
 is called also by threads which have locks on pages. To avoid deadlocks, we
@@ -1414,7 +1417,7 @@ buf_flush_free_margin(void)
 }
 
 #if defined UNIV_DEBUG || defined UNIV_BUF_DEBUG
-/**********************************************************************
+/******************************************************************//**
 Validates the flush list.
 @return	TRUE if ok */
 static
@@ -1464,7 +1467,7 @@ buf_flush_validate_low(void)
 	return(TRUE);
 }
 
-/**********************************************************************
+/******************************************************************//**
 Validates the flush list.
 @return	TRUE if ok */
 UNIV_INTERN

buf/buf0rea.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file buf/buf0rea.c
 The database buffer read
 
 Created 11/5/1995 Heikki Tuuri
@@ -35,36 +36,36 @@ Created 11/5/1995 Heikki Tuuri
 #include "trx0sys.h"
 #include "os0file.h"
 #include "srv0start.h"
+#include "srv0srv.h"
 
-extern ulint srv_read_ahead_rnd;
-extern ulint srv_read_ahead_seq;
-extern ulint srv_buf_pool_reads;
-
-/* The size in blocks of the area where the random read-ahead algorithm counts
+/** The size in blocks of the area where the random read-ahead algorithm counts
 the accessed pages when deciding whether to read-ahead */
 #define	BUF_READ_AHEAD_RANDOM_AREA	BUF_READ_AHEAD_AREA
 
-/* There must be at least this many pages in buf_pool in the area to start
+/** There must be at least this many pages in buf_pool in the area to start
 a random read-ahead */
 #define BUF_READ_AHEAD_RANDOM_THRESHOLD	(5 + buf_read_ahead_random_area / 8)
 
-/* The linear read-ahead area size */
+/** The linear read-ahead area size */
 #define	BUF_READ_AHEAD_LINEAR_AREA	BUF_READ_AHEAD_AREA
 
-/* The linear read-ahead threshold */
+/** The linear read-ahead threshold */
 #define LINEAR_AREA_THRESHOLD_COEF	5 / 8
 
-/* If there are buf_pool->curr_size per the number below pending reads, then
+/** If there are buf_pool->curr_size per the number below pending reads, then
 read-ahead is not done: this is to prevent flooding the buffer pool with
 i/o-fixed buffer blocks */
 #define BUF_READ_AHEAD_PEND_LIMIT	2
 
-/************************************************************************
+/********************************************************************//**
 Low-level function which reads a page asynchronously from a file to the
 buffer buf_pool if it is not already there, in which case does nothing.
 Sets the io_fix flag and sets an exclusive lock on the buffer frame. The
 flag is cleared and the x-lock released by an i/o-handler thread.
-@return	1 if a read request was queued, 0 if the page already resided in buf_pool, or if the page is in the doublewrite buffer blocks in which case it is never read into the pool, or if the tablespace does not exist or is being dropped */
+@return 1 if a read request was queued, 0 if the page already resided
+in buf_pool, or if the page is in the doublewrite buffer blocks in
+which case it is never read into the pool, or if the tablespace does
+not exist or is being dropped */
 static
 ulint
 buf_read_page_low(
@@ -166,7 +167,7 @@ buf_read_page_low(
 	return(1);
 }
 
-/************************************************************************
+/********************************************************************//**
 Applies a random read-ahead in buf_pool if there are at least a threshold
 value of accessed pages from the random read-ahead area. Does not read any
 page, not even the one at the position (space, offset), if the read-ahead
@@ -176,7 +177,9 @@ end up waiting for these latches! NOTE 2: the calling thread must want
 access to the page given: this rule is set to prevent unintended read-aheads
 performed by ibuf routines, a situation which could result in a deadlock if
 the OS does not support asynchronous i/o.
-@return	number of page read requests issued; NOTE that if we read ibuf pages, it may happen that the page at the given page number does not get read even if we return a value > 0! */
+@return number of page read requests issued; NOTE that if we read ibuf
+pages, it may happen that the page at the given page number does not
+get read even if we return a positive value! */
 static
 ulint
 buf_read_ahead_random(
@@ -320,13 +323,14 @@ buf_read_ahead_random(
 	return(count);
 }
 
-/************************************************************************
+/********************************************************************//**
 High-level function which reads a page asynchronously from a file to the
 buffer buf_pool if it is not already there. Sets the io_fix flag and sets
 an exclusive lock on the buffer frame. The flag is cleared and the x-lock
 released by the i/o-handler thread. Does a random read-ahead if it seems
 sensible.
-@return	number of page read requests issued: this can be > 1 if read-ahead occurred */
+@return number of page read requests issued: this can be greater than
+1 if read-ahead occurred */
 UNIV_INTERN
 ulint
 buf_read_page(
@@ -370,7 +374,7 @@ buf_read_page(
 	return(count + count2);
 }
 
-/************************************************************************
+/********************************************************************//**
 Applies linear read-ahead if in the buf_pool the page is a border page of
 a linear read-ahead area and all the pages in the area have been accessed.
 Does not read any page if the read-ahead mechanism is not activated. Note
@@ -637,7 +641,7 @@ buf_read_ahead_linear(
 	return(count);
 }
 
-/************************************************************************
+/********************************************************************//**
 Issues read requests for pages which the ibuf module wants to read in, in
 order to contract the insert buffer tree. Technically, this function is like
 a read-ahead function. */
@@ -715,7 +719,7 @@ buf_read_ibuf_merge_pages(
 #endif /* UNIV_DEBUG */
 }
 
-/************************************************************************
+/********************************************************************//**
 Issues read requests for pages which recovery wants to read in. */
 UNIV_INTERN
 void

data/data0data.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/************************************************************************
+/********************************************************************//**
+@file data/data0data.c
 SQL data field and tuple
 
 Created 5/30/1994 Heikki Tuuri
@@ -40,18 +41,19 @@ Created 5/30/1994 Heikki Tuuri
 #endif /* !UNIV_HOTBACKUP */
 
 #ifdef UNIV_DEBUG
-/* data pointers of tuple fields are initialized to point here
-for error checking */
+/** Dummy variable to catch access to uninitialized fields.  In the
+debug version, dtuple_create() will make all fields of dtuple_t point
+to data_error. */
 UNIV_INTERN byte	data_error;
 
 # ifndef UNIV_DEBUG_VALGRIND
-/* this is used to fool the compiler in dtuple_validate */
+/** this is used to fool the compiler in dtuple_validate */
 UNIV_INTERN ulint	data_dummy;
 # endif /* !UNIV_DEBUG_VALGRIND */
 #endif /* UNIV_DEBUG */
 
 #ifndef UNIV_HOTBACKUP
-/*************************************************************************
+/*********************************************************************//**
 Tests if dfield data length and content is equal to the given.
 @return	TRUE if equal */
 UNIV_INTERN
@@ -80,9 +82,10 @@ dfield_data_is_binary_equal(
 	return(TRUE);
 }
 
-/****************************************************************
+/************************************************************//**
 Compare two data tuples, respecting the collation of character fields.
-@return	1, 0 , -1 if tuple1 is greater, equal, less, respectively, than tuple2 */
+@return 1, 0 , -1 if tuple1 is greater, equal, less, respectively,
+than tuple2 */
 UNIV_INTERN
 int
 dtuple_coll_cmp(
@@ -121,7 +124,7 @@ dtuple_coll_cmp(
 	return(0);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Sets number of fields used in a tuple. Normally this is set in
 dtuple_create, but if you want later to set it smaller, you can use this. */
 UNIV_INTERN
@@ -137,7 +140,7 @@ dtuple_set_n_fields(
 	tuple->n_fields_cmp = n_fields;
 }
 
-/**************************************************************
+/**********************************************************//**
 Checks that a data field is typed.
 @return	TRUE if ok */
 static
@@ -159,7 +162,7 @@ dfield_check_typed_no_assert(
 	return(TRUE);
 }
 
-/**************************************************************
+/**********************************************************//**
 Checks that a data tuple is typed.
 @return	TRUE if ok */
 UNIV_INTERN
@@ -197,7 +200,7 @@ dtuple_check_typed_no_assert(
 #endif /* !UNIV_HOTBACKUP */
 
 #ifdef UNIV_DEBUG
-/**************************************************************
+/**********************************************************//**
 Checks that a data field is typed. Asserts an error if not.
 @return	TRUE if ok */
 UNIV_INTERN
@@ -220,7 +223,7 @@ dfield_check_typed(
 	return(TRUE);
 }
 
-/**************************************************************
+/**********************************************************//**
 Checks that a data tuple is typed. Asserts an error if not.
 @return	TRUE if ok */
 UNIV_INTERN
@@ -242,7 +245,7 @@ dtuple_check_typed(
 	return(TRUE);
 }
 
-/**************************************************************
+/**********************************************************//**
 Validates the consistency of a tuple which must be complete, i.e,
 all fields must have been set.
 @return	TRUE if ok */
@@ -295,7 +298,7 @@ dtuple_validate(
 #endif /* UNIV_DEBUG */
 
 #ifndef UNIV_HOTBACKUP
-/*****************************************************************
+/*************************************************************//**
 Pretty prints a dfield value according to its data type. */
 UNIV_INTERN
 void
@@ -337,7 +340,7 @@ dfield_print(
 	}
 }
 
-/*****************************************************************
+/*************************************************************//**
 Pretty prints a dfield value according to its data type. Also the hex string
 is printed if a string contains non-printable characters. */
 UNIV_INTERN
@@ -509,7 +512,7 @@ dfield_print_also_hex(
 	}
 }
 
-/*****************************************************************
+/*************************************************************//**
 Print a dfield value using ut_print_buf. */
 static
 void
@@ -532,7 +535,7 @@ dfield_print_raw(
 	}
 }
 
-/**************************************************************
+/**********************************************************//**
 The following function prints the contents of a tuple. */
 UNIV_INTERN
 void
@@ -560,12 +563,14 @@ dtuple_print(
 	ut_ad(dtuple_validate(tuple));
 }
 
-/******************************************************************
+/**************************************************************//**
 Moves parts of long fields in entry to the big record vector so that
 the size of tuple drops below the maximum record size allowed in the
 database. Moves data only from those fields which are not necessary
 to determine uniquely the insertion place of the tuple in the index.
-@return	own: created big record vector, NULL if we are not able to shorten the entry enough, i.e., if there are too many fixed-length or short fields in entry or the index is clustered */
+@return own: created big record vector, NULL if we are not able to
+shorten the entry enough, i.e., if there are too many fixed-length or
+short fields in entry or the index is clustered */
 UNIV_INTERN
 big_rec_t*
 dtuple_convert_big_rec(
@@ -719,7 +724,7 @@ dtuple_convert_big_rec(
 	return(vector);
 }
 
-/******************************************************************
+/**************************************************************//**
 Puts back to entry the data stored in vector. Note that to ensure the
 fields in entry can accommodate the data, vector must have been created
 from entry with dtuple_convert_big_rec. */

data/data0type.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file data/data0type.c
 Data types
 
 Created 1/16/1996 Heikki Tuuri
@@ -38,7 +39,7 @@ charset-collation code for them. */
 
 UNIV_INTERN ulint	data_mysql_default_charset_coll;
 
-/*************************************************************************
+/*********************************************************************//**
 Determine how many bytes the first n characters of the given string occupy.
 If the string is shorter than n characters, returns the number of bytes
 the characters in the string occupy.
@@ -79,7 +80,7 @@ dtype_get_at_most_n_mbchars(
 }
 #endif /* UNIV_HOTBACKUP */
 
-/*************************************************************************
+/*********************************************************************//**
 Checks if a data main type is a string type. Also a BLOB is considered a
 string type.
 @return	TRUE if string type */
@@ -99,7 +100,7 @@ dtype_is_string_type(
 	return(FALSE);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Checks if a type is a binary string type. Note that for tables created with
 < 4.0.14, we do not know if a DATA_BLOB column is a BLOB or a TEXT column. For
 those DATA_BLOB columns this function currently returns FALSE.
@@ -121,7 +122,7 @@ dtype_is_binary_string_type(
 	return(FALSE);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Checks if a type is a non-binary string type. That is, dtype_is_string_type is
 TRUE and dtype_is_binary_string_type is FALSE. Note that for tables created
 with < 4.0.14, we do not know if a DATA_BLOB column is a BLOB or a TEXT column.
@@ -143,9 +144,10 @@ dtype_is_non_binary_string_type(
 	return(FALSE);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Forms a precise type from the < 4.1.2 format precise type plus the
-charset-collation code. */
+charset-collation code.
+@return precise type, including the charset-collation code */
 UNIV_INTERN
 ulint
 dtype_form_prtype(
@@ -160,7 +162,7 @@ dtype_form_prtype(
 	return(old_prtype + (charset_coll << 16));
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Validates a data type structure.
 @return	TRUE if ok */
 UNIV_INTERN
@@ -185,7 +187,7 @@ dtype_validate(
 }
 
 #ifndef UNIV_HOTBACKUP
-/*************************************************************************
+/*********************************************************************//**
 Prints a data type structure. */
 UNIV_INTERN
 void

dict/dict0boot.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file dict/dict0boot.c
 Data dictionary creation and booting
 
 Created 4/18/1996 Heikki Tuuri
@@ -39,7 +40,7 @@ Created 4/18/1996 Heikki Tuuri
 #include "log0recv.h"
 #include "os0file.h"
 
-/**************************************************************************
+/**********************************************************************//**
 Gets a pointer to the dictionary header and x-latches its page.
 @return	pointer to the dictionary header, page x-latched */
 UNIV_INTERN
@@ -60,7 +61,7 @@ dict_hdr_get(
 	return(header);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Returns a new table, index, or tree id.
 @return	the new id */
 UNIV_INTERN
@@ -89,7 +90,7 @@ dict_hdr_get_new_id(
 	return(id);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Writes the current value of the row id counter to the dictionary header file
 page. */
 UNIV_INTERN
@@ -114,7 +115,7 @@ dict_hdr_flush_row_id(void)
 	mtr_commit(&mtr);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Creates the file page for the dictionary header. This function is
 called only at the database creation.
 @return	TRUE if succeed */
@@ -217,7 +218,7 @@ dict_hdr_create(
 	return(TRUE);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Initializes the data dictionary memory structures when the database is
 started. This function is also called when the data dictionary is created. */
 UNIV_INTERN
@@ -429,7 +430,7 @@ dict_boot(void)
 	mutex_exit(&(dict_sys->mutex));
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Inserts the basic system table data into themselves in the database
 creation. */
 static
@@ -440,7 +441,7 @@ dict_insert_initial_data(void)
 	/* Does nothing yet */
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Creates and initializes the data dictionary at the database creation. */
 UNIV_INTERN
 void

dict/dict0crea.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file dict/dict0crea.c
 Database object creation
 
 Created 1/8/1996 Heikki Tuuri
@@ -42,7 +43,7 @@ Created 1/8/1996 Heikki Tuuri
 #include "usr0sess.h"
 #include "ut0vec.h"
 
-/*********************************************************************
+/*****************************************************************//**
 Based on a table object, this function builds the entry to be inserted
 in the SYS_TABLES system table.
 @return	the tuple which should be inserted */
@@ -134,7 +135,7 @@ dict_create_sys_tables_tuple(
 	return(entry);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Based on a table object, this function builds the entry to be inserted
 in the SYS_COLUMNS system table.
 @return	the tuple which should be inserted */
@@ -216,7 +217,7 @@ dict_create_sys_columns_tuple(
 	return(entry);
 }
 
-/*******************************************************************
+/***************************************************************//**
 Builds a table definition to insert.
 @return	DB_SUCCESS or error code */
 static
@@ -295,7 +296,7 @@ dict_build_table_def_step(
 	return(DB_SUCCESS);
 }
 
-/*******************************************************************
+/***************************************************************//**
 Builds a column definition to insert.
 @return	DB_SUCCESS */
 static
@@ -313,7 +314,7 @@ dict_build_col_def_step(
 	return(DB_SUCCESS);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Based on an index object, this function builds the entry to be inserted
 in the SYS_INDEXES system table.
 @return	the tuple which should be inserted */
@@ -403,7 +404,7 @@ dict_create_sys_indexes_tuple(
 	return(entry);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Based on an index object, this function builds the entry to be inserted
 in the SYS_FIELDS system table.
 @return	the tuple which should be inserted */
@@ -479,7 +480,7 @@ dict_create_sys_fields_tuple(
 	return(entry);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Creates the tuple with which the index entry is searched for writing the index
 tree root page number, if such a tree is created.
 @return	the tuple for search */
@@ -515,7 +516,7 @@ dict_create_search_tuple(
 	return(search_tuple);
 }
 
-/*******************************************************************
+/***************************************************************//**
 Builds an index definition row to insert.
 @return	DB_SUCCESS or error code */
 static
@@ -567,7 +568,7 @@ dict_build_index_def_step(
 	return(DB_SUCCESS);
 }
 
-/*******************************************************************
+/***************************************************************//**
 Builds a field definition row to insert.
 @return	DB_SUCCESS */
 static
@@ -588,7 +589,7 @@ dict_build_field_def_step(
 	return(DB_SUCCESS);
 }
 
-/*******************************************************************
+/***************************************************************//**
 Creates an index tree for the index if it is not a member of a cluster.
 @return	DB_SUCCESS or DB_OUT_OF_FILE_SPACE */
 static
@@ -645,7 +646,7 @@ dict_create_index_tree_step(
 	return(DB_SUCCESS);
 }
 
-/***********************************************************************
+/*******************************************************************//**
 Drops the index tree associated with a row in SYS_INDEXES table. */
 UNIV_INTERN
 void
@@ -708,7 +709,7 @@ dict_drop_index_tree(
 				     FIL_NULL, mtr);
 }
 
-/***********************************************************************
+/*******************************************************************//**
 Truncates the index tree associated with a row in SYS_INDEXES table.
 @return	new root page number, or FIL_NULL on failure */
 UNIV_INTERN
@@ -843,7 +844,7 @@ dict_truncate_index_tree(
 	return(FIL_NULL);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Creates a table create graph.
 @return	own: table create node */
 UNIV_INTERN
@@ -879,7 +880,7 @@ tab_create_graph_create(
 	return(node);
 }
 
-/*************************************************************************
+/*********************************************************************//**
 Creates an index create graph.
 @return	own: index create node */
 UNIV_INTERN
@@ -916,7 +917,7 @@ ind_create_graph_create(
 	return(node);
 }
 
-/***************************************************************
+/***********************************************************//**
 Creates a table. This is a high-level function used in SQL execution graphs.
 @return	query thread to run next or NULL */
 UNIV_INTERN
@@ -1022,7 +1023,7 @@ dict_create_table_step(
 	return(thr);
 }
 
-/***************************************************************
+/***********************************************************//**
 Creates an index. This is a high-level function used in SQL execution
 graphs.
 @return	query thread to run next or NULL */
@@ -1153,7 +1154,7 @@ dict_create_index_step(
 	return(thr);
 }
 
-/********************************************************************
+/****************************************************************//**
 Creates the foreign key constraints system tables inside InnoDB
 at database creation or database start if they are not found or are
 not of the right form.
@@ -1274,7 +1275,7 @@ dict_create_or_check_foreign_constraint_tables(void)
 	return(error);
 }
 
-/********************************************************************
+/****************************************************************//**
 Evaluate the given foreign key SQL statement.
 @return	error code or DB_SUCCESS */
 static
@@ -1339,7 +1340,7 @@ dict_foreign_eval_sql(
 	return(DB_SUCCESS);
 }
 
-/************************************************************************
+/********************************************************************//**
 Add a single foreign key field definition to the data dictionary tables in
 the database.
 @return	error code or DB_SUCCESS */
@@ -1374,7 +1375,7 @@ dict_create_add_foreign_field_to_dictionary(
 		       table, foreign, trx));
 }
 
-/************************************************************************
+/********************************************************************//**
 Add a single foreign key definition to the data dictionary tables in the
 database. We also generate names to constraints that were not named by the
 user. A generated constraint has a name of the format
@@ -1449,7 +1450,7 @@ dict_create_add_foreign_to_dictionary(
 	return(error);
 }
 
-/************************************************************************
+/********************************************************************//**
 Adds foreign key definitions to data dictionary tables in the database.
 @return	error code or DB_SUCCESS */
 UNIV_INTERN

dict/dict0load.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file dict/dict0load.c
 Loads to the memory cache database object definitions
 from dictionary tables
 
@@ -40,17 +41,17 @@ Created 4/24/1996 Heikki Tuuri
 #include "srv0start.h"
 #include "srv0srv.h"
 
-/********************************************************************
-Returns TRUE if index's i'th column's name is 'name' .
-@return	 */
+/****************************************************************//**
+Compare the name of an index column.
+@return	TRUE if the i'th column of index is 'name'. */
 static
 ibool
 name_of_col_is(
 /*===========*/
-	dict_table_t*	table,	/*!< in: table */
-	dict_index_t*	index,	/*!< in: index */
-	ulint		i,	/*!< in:  */
-	const char*	name)	/*!< in: name to compare to */
+	const dict_table_t*	table,	/*!< in: table */
+	const dict_index_t*	index,	/*!< in: index */
+	ulint			i,	/*!< in: index field offset */
+	const char*		name)	/*!< in: name to compare to */
 {
 	ulint	tmp = dict_col_get_no(dict_field_get_col(
 					      dict_index_get_nth_field(
@@ -59,9 +60,10 @@ name_of_col_is(
 	return(strcmp(name, dict_table_get_col_name(table, tmp)) == 0);
 }
 
-/************************************************************************
+/********************************************************************//**
 Finds the first table name in the given database.
-@return	own: table name, NULL if does not exist; the caller must free the memory in the string! */
+@return own: table name, NULL if does not exist; the caller must free
+the memory in the string! */
 UNIV_INTERN
 char*
 dict_get_first_table_name_in_db(
@@ -141,7 +143,7 @@ dict_get_first_table_name_in_db(
 	goto loop;
 }
 
-/************************************************************************
+/********************************************************************//**
 Prints to the standard output information on all tables found in the data
 dictionary system table. */
 UNIV_INTERN
@@ -234,9 +236,10 @@ dict_print(void)
 	goto loop;
 }
 
-/************************************************************************
+/********************************************************************//**
 Determine the flags of a table described in SYS_TABLES.
-@return	compressed page size in kilobytes; or 0 if the tablespace is uncompressed, ULINT_UNDEFINED on error */
+@return compressed page size in kilobytes; or 0 if the tablespace is
+uncompressed, ULINT_UNDEFINED on error */
 static
 ulint
 dict_sys_tables_get_flags(
@@ -295,7 +298,7 @@ dict_sys_tables_get_flags(
 	return(flags);
 }
 
-/************************************************************************
+/********************************************************************//**
 In a crash recovery we already have all the tablespace objects created.
 This function compares the space id information in the InnoDB data dictionary
 to what we already read with fil_load_single_table_tablespaces().
@@ -417,7 +420,7 @@ dict_check_tablespaces_and_store_max_id(
 	goto loop;
 }
 
-/************************************************************************
+/********************************************************************//**
 Loads definitions for table columns. */
 static
 void
@@ -523,7 +526,7 @@ dict_load_columns(
 	mtr_commit(&mtr);
 }
 
-/************************************************************************
+/********************************************************************//**
 Loads definitions for index fields. */
 static
 void
@@ -624,10 +627,11 @@ dict_load_fields(
 	mtr_commit(&mtr);
 }
 
-/************************************************************************
+/********************************************************************//**
 Loads definitions for table indexes. Adds them to the data dictionary
 cache.
-@return	DB_SUCCESS if ok, DB_CORRUPTION if corruption of dictionary table or DB_UNSUPPORTED if table has unknown index type */
+@return DB_SUCCESS if ok, DB_CORRUPTION if corruption of dictionary
+table or DB_UNSUPPORTED if table has unknown index type */
 static
 ulint
 dict_load_indexes(
@@ -796,13 +800,15 @@ dict_load_indexes(
 	return(error);
 }
 
-/************************************************************************
+/********************************************************************//**
 Loads a table definition and also all its index definitions, and also
 the cluster definition if the table is a member in a cluster. Also loads
 all foreign key constraints where the foreign key is in the table or where
 a foreign key references columns in this table. Adds all these to the data
 dictionary cache.
-@return	table, NULL if does not exist; if the table is stored in an .ibd file, but the file does not exist, then we set the ibd_file_missing flag TRUE in the table object we return */
+@return table, NULL if does not exist; if the table is stored in an
+.ibd file, but the file does not exist, then we set the
+ibd_file_missing flag TRUE in the table object we return */
 UNIV_INTERN
 dict_table_t*
 dict_load_table(
@@ -987,7 +993,7 @@ dict_load_table(
 	return(table);
 }
 
-/***************************************************************************
+/***********************************************************************//**
 Loads a table object based on the table id.
 @return	table; NULL if table does not exist */
 UNIV_INTERN
@@ -1078,7 +1084,7 @@ dict_load_table_on_id(
 	return(table);
 }
 
-/************************************************************************
+/********************************************************************//**
 This function is called when the database is booted. Loads system table
 index definitions except for the clustered index which is added to the
 dictionary cache at booting before calling this function. */
@@ -1099,7 +1105,7 @@ dict_load_sys_table(
 	mem_heap_free(heap);
 }
 
-/************************************************************************
+/********************************************************************//**
 Loads foreign key constraint col names (also for the referenced table). */
 static
 void
@@ -1171,7 +1177,7 @@ dict_load_foreign_cols(
 	mtr_commit(&mtr);
 }
 
-/***************************************************************************
+/***********************************************************************//**
 Loads a foreign key constraint to the dictionary cache.
 @return	DB_SUCCESS or error code */
 static
@@ -1296,7 +1302,7 @@ dict_load_foreign(
 	return(dict_foreign_add_to_cache(foreign, check_charsets));
 }
 
-/***************************************************************************
+/***********************************************************************//**
 Loads foreign key constraints where the table is either the foreign key
 holder or where the table is referenced by a foreign key. Adds these
 constraints to the data dictionary. Note that we know that the dictionary

dict/dict0mem.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/**********************************************************************
+/******************************************************************//**
+@file dict/dict0mem.c
 Data dictionary memory object creation
 
 Created 1/8/1996 Heikki Tuuri
@@ -36,10 +37,10 @@ Created 1/8/1996 Heikki Tuuri
 # include "lock0lock.h"
 #endif /* !UNIV_HOTBACKUP */
 
-#define	DICT_HEAP_SIZE		100	/* initial memory heap size when
+#define	DICT_HEAP_SIZE		100	/*!< initial memory heap size when
 					creating a table or index object */
 
-/**************************************************************************
+/**********************************************************************//**
 Creates a table memory object.
 @return	own: table object */
 UNIV_INTERN
@@ -90,7 +91,7 @@ dict_mem_table_create(
 	return(table);
 }
 
-/********************************************************************
+/****************************************************************//**
 Free a table memory object. */
 UNIV_INTERN
 void
@@ -106,8 +107,8 @@ dict_mem_table_free(
 	mem_heap_free(table->heap);
 }
 
-/********************************************************************
-Append 'name' to 'col_names' (@see dict_table_t::col_names).
+/****************************************************************//**
+Append 'name' to 'col_names'.  @see dict_table_t::col_names
 @return	new column names array */
 static
 const char*
@@ -154,7 +155,7 @@ dict_add_col_name(
 	return(res);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Adds a column definition to a table. */
 UNIV_INTERN
 void
@@ -211,7 +212,7 @@ dict_mem_table_add_col(
 #endif /* !UNIV_HOTBACKUP */
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Creates an index memory object.
 @return	own: index object */
 UNIV_INTERN
@@ -254,7 +255,7 @@ dict_mem_index_create(
 	return(index);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Creates and initializes a foreign constraint memory object.
 @return	own: foreign constraint struct */
 UNIV_INTERN
@@ -274,7 +275,7 @@ dict_mem_foreign_create(void)
 	return(foreign);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Adds a field definition to an index. NOTE: does not take a copy
 of the column name if the field is a column. The memory occupied
 by the column name may be released only after publishing the index. */
@@ -301,7 +302,7 @@ dict_mem_index_add_field(
 	field->prefix_len = (unsigned int) prefix_len;
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Frees an index memory object. */
 UNIV_INTERN
 void

dyn/dyn0dyn.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file dyn/dyn0dyn.c
 The dynamically allocated array
 
 Created 2/5/1996 Heikki Tuuri
@@ -27,7 +28,7 @@ Created 2/5/1996 Heikki Tuuri
 #include "dyn0dyn.ic"
 #endif
 
-/****************************************************************
+/************************************************************//**
 Adds a new block to a dyn array.
 @return	created block */
 UNIV_INTERN

eval/eval0eval.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file eval/eval0eval.c
 SQL evaluator: evaluates simple data structures, like expressions, in
 a query graph
 
@@ -32,15 +33,15 @@ Created 12/29/1997 Heikki Tuuri
 #include "data0data.h"
 #include "row0sel.h"
 
-/* The RND function seed */
+/** The RND function seed */
 static ulint	eval_rnd	= 128367121;
 
-/* Dummy adress used when we should allocate a buffer of size 0 in
-the function below */
+/** Dummy adress used when we should allocate a buffer of size 0 in
+eval_node_alloc_val_buf */
 
 static byte	eval_dummy;
 
-/*********************************************************************
+/*****************************************************************//**
 Allocate a buffer from global dynamic memory for a value of a que_node.
 NOTE that this memory must be explicitly freed when the query graph is
 freed. If the node already has an allocated buffer, that buffer is freed
@@ -83,7 +84,7 @@ eval_node_alloc_val_buf(
 	return(data);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Free the buffer from global dynamic memory for a value of a que_node,
 if it has been allocated in the above function. The freeing for pushed
 column values is done in sel_col_prefetch_buf_free. */
@@ -110,7 +111,7 @@ eval_node_free_val_buf(
 	}
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a comparison node.
 @return	the result of the comparison */
 UNIV_INTERN
@@ -169,7 +170,7 @@ eval_cmp(
 	return(val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a logical operation node. */
 UNIV_INLINE
 void
@@ -210,7 +211,7 @@ eval_logical(
 	eval_node_set_ibool_val(logical_node, val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates an arithmetic operation node. */
 UNIV_INLINE
 void
@@ -254,7 +255,7 @@ eval_arith(
 	eval_node_set_int_val(arith_node, val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates an aggregate operation node. */
 UNIV_INLINE
 void
@@ -288,7 +289,7 @@ eval_aggregate(
 	eval_node_set_int_val(node, val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a predefined function node where the function is not relevant
 in benchmarks. */
 static
@@ -375,7 +376,7 @@ eval_predefined_2(
 	}
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a notfound-function node. */
 UNIV_INLINE
 void
@@ -417,7 +418,7 @@ eval_notfound(
 	eval_node_set_ibool_val(func_node, ibool_val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a substr-function node. */
 UNIV_INLINE
 void
@@ -450,7 +451,7 @@ eval_substr(
 	dfield_set_data(dfield, str1 + len1, len2);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a replstr-procedure node. */
 static
 void
@@ -490,7 +491,7 @@ eval_replstr(
 	ut_memcpy(str1 + len1, str2, len2);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates an instr-function node. */
 static
 void
@@ -562,7 +563,7 @@ eval_instr(
 	eval_node_set_int_val(func_node, int_val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a predefined function node. */
 UNIV_INLINE
 void
@@ -600,7 +601,7 @@ eval_binary_to_number(
 	eval_node_copy_and_alloc_val(func_node, str2, 4);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a predefined function node. */
 static
 void
@@ -642,7 +643,7 @@ eval_concat(
 	}
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a predefined function node. If the first argument is an integer,
 this function looks at the second argument which is the integer length in
 bytes, and converts the integer to a VARCHAR.
@@ -690,7 +691,7 @@ eval_to_binary(
 	dfield_set_data(dfield, str1 + (4 - len1), len1);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a predefined function node. */
 UNIV_INLINE
 void
@@ -782,7 +783,7 @@ eval_predefined(
 	eval_node_set_int_val(func_node, int_val);
 }
 
-/*********************************************************************
+/*****************************************************************//**
 Evaluates a function node. */
 UNIV_INTERN
 void

eval/eval0proc.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file eval/eval0proc.c
 Executes SQL stored procedures and their control structures
 
 Created 1/20/1998 Heikki Tuuri
@@ -28,7 +29,7 @@ Created 1/20/1998 Heikki Tuuri
 #include "eval0proc.ic"
 #endif
 
-/**************************************************************************
+/**********************************************************************//**
 Performs an execution step of an if-statement node.
 @return	query thread to run next or NULL */
 UNIV_INTERN
@@ -104,7 +105,7 @@ if_step(
 	return(thr);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Performs an execution step of a while-statement node.
 @return	query thread to run next or NULL */
 UNIV_INTERN
@@ -140,7 +141,7 @@ while_step(
 	return(thr);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Performs an execution step of an assignment statement node.
 @return	query thread to run next or NULL */
 UNIV_INTERN
@@ -167,7 +168,7 @@ assign_step(
 	return(thr);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Performs an execution step of a for-loop node.
 @return	query thread to run next or NULL */
 UNIV_INTERN
@@ -229,7 +230,7 @@ for_step(
 	return(thr);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Performs an execution step of an exit statement node.
 @return	query thread to run next or NULL */
 UNIV_INTERN
@@ -261,7 +262,7 @@ exit_step(
 	return(thr);
 }
 
-/**************************************************************************
+/**********************************************************************//**
 Performs an execution step of a return-statement node.
 @return	query thread to run next or NULL */
 UNIV_INTERN

fut/fut0fut.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/**********************************************************************
+/******************************************************************//**
+@file fut/fut0fut.c
 File-based utilities
 
 Created 12/13/1995 Heikki Tuuri

ha/ha0storage.c

@@ -16,7 +16,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/******************************************************
+/**************************************************//**
+@file ha/ha0storage.c
 Hash storage.
 Provides a data structure that stores chunks of data in
 its own storage, avoiding duplicates.
@@ -34,7 +35,7 @@ Created September 22, 2007 Vasil Dimov
 #include "ha0storage.ic"
 #endif
 
-/***********************************************************************
+/*******************************************************************//**
 Retrieves a data from a storage. If it is present, a pointer to the
 stored copy of data is returned, otherwise NULL is returned. */
 static
@@ -73,7 +74,7 @@ ha_storage_get(
 	return(node->data);
 }
 
-/***********************************************************************
+/*******************************************************************//**
 Copies data into the storage and returns a pointer to the copy. If the
 same data chunk is already present, then pointer to it is returned.
 Data chunks are considered to be equal if len1 == len2 and

handler/handler0vars.h

@@ -16,12 +16,13 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/***********************************************************************
+/*******************************************************************//**
+@file handler/handler0vars.h
 This file contains accessor functions for dynamic plugin on Windows.
 ***********************************************************************/
 
 #if defined __WIN__ && defined MYSQL_DYNAMIC_PLUGIN
-/***********************************************************************
+/*******************************************************************//**
 This is a list of externals that can not be resolved by delay loading.
 They have to be resolved indirectly via their addresses in the .map file.
 All of them are external variables. */