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

(Ran doxygenify.pl conversion locally, then merged and checked consistency.)
  ------------------------------------------------------------------------
  r5091 | marko | 2009-05-25 09:30:14 +0300 (Mon, 25 May 2009) | 33 lines

  branches/zip: Convert the function comments to Doxygen format.

  This patch was created by running the following commands:

  for i in */*[ch]; do doxygenify.pl $i; done
  perl -i -pe 's#\*{3} \*/$#****/#' */*[ch]

  where doxygenify.pl is
  https://svn.innodb.com/svn/misc/trunk/tools/doxygenify.pl r510

  Verified the consistency as follows:

  (0) not too many /* in: */ or /* out: */ comments left in the code:
  grep -l '/\*\s*\(in\|out\)[,:/]' */*[ch]

  (1) no difference when ignoring blank lines, after stripping all
  C90-style /* comments */, including multi-line ones, before and after
  applying this patch:

  perl -i -e 'undef $/;while(<ARGV>){s#/\*(.*?)\*/##gs;print}' */*[ch]
  diff -I'^\s*$' --exclude .svn -ru TREE1 TREE2

  (2) after stripping @return comments and !<, generated a diff and omitted
  the hunks where /* out: */ function return comments were removed:

  perl -i -e'undef $/;while(<ARGV>){s#!<##g;s#\n\@return\t.*?\*/# \*/#gs;print}'\
   */*[ch]
  svn diff|
  perl -e 'undef $/;$_=<>;s#\n-\s*/\* out[:,]([^\n]*?)(\n-[^\n]*?)*\*/##gs;print'

  Some unintended changes were left.  These will be removed in a
  subsequent patch.
  ------------------------------------------------------------------------

btr/btr0pcur.c

@@ -33,12 +33,12 @@ Created 2/23/1996 Heikki Tuuri
 #include "trx0trx.h"
 
 /******************************************************************
-Allocates memory for a persistent cursor object and initializes the cursor. */
+Allocates memory for a persistent cursor object and initializes the cursor.
+@return	own: persistent cursor */
 UNIV_INTERN
 btr_pcur_t*
 btr_pcur_create_for_mysql(void)
 /*============================*/
-				/* out, own: persistent cursor */
 {
 	btr_pcur_t*	pcur;
 
@@ -56,7 +56,7 @@ UNIV_INTERN
 void
 btr_pcur_free_for_mysql(
 /*====================*/
-	btr_pcur_t*	cursor)	/* in, own: persistent cursor */
+	btr_pcur_t*	cursor)	/*!< in, own: persistent cursor */
 {
 	if (cursor->old_rec_buf != NULL) {
 
@@ -87,8 +87,8 @@ UNIV_INTERN
 void
 btr_pcur_store_position(
 /*====================*/
-	btr_pcur_t*	cursor, /* in: persistent cursor */
-	mtr_t*		mtr)	/* in: mtr */
+	btr_pcur_t*	cursor, /*!< in: persistent cursor */
+	mtr_t*		mtr)	/*!< in: mtr */
 {
 	page_cur_t*	page_cursor;
 	buf_block_t*	block;
@@ -163,9 +163,9 @@ UNIV_INTERN
 void
 btr_pcur_copy_stored_position(
 /*==========================*/
-	btr_pcur_t*	pcur_receive,	/* in: pcur which will receive the
+	btr_pcur_t*	pcur_receive,	/*!< in: pcur which will receive the
 					position info */
-	btr_pcur_t*	pcur_donate)	/* in: pcur from which the info is
+	btr_pcur_t*	pcur_donate)	/*!< in: pcur from which the info is
 					copied */
 {
 	if (pcur_receive->old_rec_buf) {
@@ -198,19 +198,15 @@ infimum;
 (3) cursor was positioned on the page supremum: restores to the first record
 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. */
+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 */
 UNIV_INTERN
 ibool
 btr_pcur_restore_position(
 /*======================*/
-					/* out: 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 */
-	ulint		latch_mode,	/* in: BTR_SEARCH_LEAF, ... */
-	btr_pcur_t*	cursor,		/* in: detached persistent cursor */
-	mtr_t*		mtr)		/* in: mtr */
+	ulint		latch_mode,	/*!< in: BTR_SEARCH_LEAF, ... */
+	btr_pcur_t*	cursor,		/*!< in: detached persistent cursor */
+	mtr_t*		mtr)		/*!< in: mtr */
 {
 	dict_index_t*	index;
 	dtuple_t*	tuple;
@@ -361,8 +357,8 @@ UNIV_INTERN
 void
 btr_pcur_release_leaf(
 /*==================*/
-	btr_pcur_t*	cursor, /* in: persistent cursor */
-	mtr_t*		mtr)	/* in: mtr */
+	btr_pcur_t*	cursor, /*!< in: persistent cursor */
+	mtr_t*		mtr)	/*!< in: mtr */
 {
 	buf_block_t*	block;
 
@@ -387,9 +383,9 @@ UNIV_INTERN
 void
 btr_pcur_move_to_next_page(
 /*=======================*/
-	btr_pcur_t*	cursor,	/* in: persistent cursor; must be on the
+	btr_pcur_t*	cursor,	/*!< in: persistent cursor; must be on the
 				last record of the current page */
-	mtr_t*		mtr)	/* in: mtr */
+	mtr_t*		mtr)	/*!< in: mtr */
 {
 	ulint		next_page_no;
 	ulint		space;
@@ -442,9 +438,9 @@ UNIV_INTERN
 void
 btr_pcur_move_backward_from_page(
 /*=============================*/
-	btr_pcur_t*	cursor,	/* in: persistent cursor, must be on the first
+	btr_pcur_t*	cursor,	/*!< in: persistent cursor, must be on the first
 				record of the current page */
-	mtr_t*		mtr)	/* in: mtr */
+	mtr_t*		mtr)	/*!< in: mtr */
 {
 	ulint		prev_page_no;
 	ulint		space;
@@ -513,16 +509,15 @@ btr_pcur_move_backward_from_page(
 
 /*************************************************************
 Moves the persistent cursor to the previous record in the tree. If no records
-are left, the cursor stays 'before first in tree'. */
+are left, the cursor stays 'before first in tree'.
+@return	TRUE if the cursor was not before first in tree */
 UNIV_INTERN
 ibool
 btr_pcur_move_to_prev(
 /*==================*/
-				/* out: TRUE if the cursor was not before first
-				in tree */
-	btr_pcur_t*	cursor,	/* in: persistent cursor; NOTE that the
+	btr_pcur_t*	cursor,	/*!< in: persistent cursor; NOTE that the
 				function may release the page latch */
-	mtr_t*		mtr)	/* in: mtr */
+	mtr_t*		mtr)	/*!< in: mtr */
 {
 	ut_ad(cursor->pos_state == BTR_PCUR_IS_POSITIONED);
 	ut_ad(cursor->latch_mode != BTR_NO_LATCHES);
@@ -557,14 +552,14 @@ UNIV_INTERN
 void
 btr_pcur_open_on_user_rec(
 /*======================*/
-	dict_index_t*	index,		/* in: index */
-	const dtuple_t*	tuple,		/* in: tuple on which search done */
-	ulint		mode,		/* in: PAGE_CUR_L, ... */
-	ulint		latch_mode,	/* in: BTR_SEARCH_LEAF or
+	dict_index_t*	index,		/*!< in: index */
+	const dtuple_t*	tuple,		/*!< in: tuple on which search done */
+	ulint		mode,		/*!< in: PAGE_CUR_L, ... */
+	ulint		latch_mode,	/*!< in: BTR_SEARCH_LEAF or
 					BTR_MODIFY_LEAF */
-	btr_pcur_t*	cursor,		/* in: memory buffer for persistent
+	btr_pcur_t*	cursor,		/*!< in: memory buffer for persistent
 					cursor */
-	mtr_t*		mtr)		/* in: mtr */
+	mtr_t*		mtr)		/*!< in: mtr */
 {
 	btr_pcur_open(index, tuple, mode, latch_mode, cursor, mtr);
 

buf/buf0buddy.c

@@ -45,14 +45,14 @@ 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. */
+Get the offset of the buddy of a compressed page frame.
+@return	the buddy relative of page */
 UNIV_INLINE
 byte*
 buf_buddy_get(
 /*==========*/
-			/* out: the buddy relative of page */
-	byte*	page,	/* in: compressed page */
-	ulint	size)	/* in: page size in bytes */
+	byte*	page,	/*!< in: compressed page */
+	ulint	size)	/*!< in: page size in bytes */
 {
 	ut_ad(ut_is_2pow(size));
 	ut_ad(size >= BUF_BUDDY_LOW);
@@ -72,8 +72,8 @@ UNIV_INLINE
 void
 buf_buddy_add_to_free(
 /*==================*/
-	buf_page_t*	bpage,	/* in,own: block to be freed */
-	ulint		i)	/* in: index of buf_pool->zip_free[] */
+	buf_page_t*	bpage,	/*!< in,own: block to be freed */
+	ulint		i)	/*!< in: index of buf_pool->zip_free[] */
 {
 #ifdef UNIV_DEBUG_VALGRIND
 	buf_page_t*	b  = UT_LIST_GET_FIRST(buf_pool->zip_free[i]);
@@ -98,8 +98,8 @@ UNIV_INLINE
 void
 buf_buddy_remove_from_free(
 /*=======================*/
-	buf_page_t*	bpage,	/* in: block to be removed */
-	ulint		i)	/* in: index of buf_pool->zip_free[] */
+	buf_page_t*	bpage,	/*!< in: block to be removed */
+	ulint		i)	/*!< in: index of buf_pool->zip_free[] */
 {
 #ifdef UNIV_DEBUG_VALGRIND
 	buf_page_t*	prev = UT_LIST_GET_PREV(list, bpage);
@@ -123,14 +123,13 @@ buf_buddy_remove_from_free(
 }
 
 /**************************************************************************
-Try to allocate a block from buf_pool->zip_free[]. */
+Try to allocate a block from buf_pool->zip_free[].
+@return	allocated block, or NULL if buf_pool->zip_free[] was empty */
 static
 void*
 buf_buddy_alloc_zip(
 /*================*/
-			/* out: allocated block, or NULL
-			if buf_pool->zip_free[] was empty */
-	ulint	i)	/* in: index of buf_pool->zip_free[] */
+	ulint	i)	/*!< in: index of buf_pool->zip_free[] */
 {
 	buf_page_t*	bpage;
 
@@ -182,7 +181,7 @@ static
 void
 buf_buddy_block_free(
 /*=================*/
-	void*	buf)	/* in: buffer frame to deallocate */
+	void*	buf)	/*!< in: buffer frame to deallocate */
 {
 	const ulint	fold	= BUF_POOL_ZIP_FOLD_PTR(buf);
 	buf_page_t*	bpage;
@@ -221,7 +220,7 @@ static
 void
 buf_buddy_block_register(
 /*=====================*/
-	buf_block_t*	block)	/* in: buffer frame to allocate */
+	buf_block_t*	block)	/*!< in: buffer frame to allocate */
 {
 	const ulint	fold = BUF_POOL_ZIP_FOLD(block);
 	ut_ad(buf_pool_mutex_own());
@@ -242,15 +241,15 @@ buf_buddy_block_register(
 }
 
 /**************************************************************************
-Allocate a block from a bigger object. */
+Allocate a block from a bigger object.
+@return	allocated block */
 static
 void*
 buf_buddy_alloc_from(
 /*=================*/
-				/* out: allocated block */
-	void*		buf,	/* in: a block that is free to use */
-	ulint		i,	/* in: index of buf_pool->zip_free[] */
-	ulint		j)	/* in: size of buf as an index
+	void*		buf,	/*!< in: a block that is free to use */
+	ulint		i,	/*!< in: index of buf_pool->zip_free[] */
+	ulint		j)	/*!< in: size of buf as an index
 				of buf_pool->zip_free[] */
 {
 	ulint	offs	= BUF_BUDDY_LOW << j;
@@ -284,16 +283,15 @@ buf_buddy_alloc_from(
 /**************************************************************************
 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. */
+The buf_pool_mutex may only be released and reacquired if lru != NULL.
+@return	allocated block, possibly NULL if lru==NULL */
 UNIV_INTERN
 void*
 buf_buddy_alloc_low(
 /*================*/
-			/* out: allocated block,
-			possibly NULL if lru==NULL */
-	ulint	i,	/* in: index of buf_pool->zip_free[],
+	ulint	i,	/*!< in: index of buf_pool->zip_free[],
 			or BUF_BUDDY_SIZES */
-	ibool*	lru)	/* in: pointer to a variable that will be assigned
+	ibool*	lru)	/*!< in: pointer to a variable that will be assigned
 			TRUE if storage was allocated from the LRU list
 			and buf_pool_mutex was temporarily released,
 			or NULL if the LRU list should not be used */
@@ -343,14 +341,14 @@ func_exit:
 }
 
 /**************************************************************************
-Try to relocate the control block of a compressed page. */
+Try to relocate the control block of a compressed page.
+@return	TRUE if relocated */
 static
 ibool
 buf_buddy_relocate_block(
 /*=====================*/
-				/* out: TRUE if relocated */
-	buf_page_t*	bpage,	/* in: block to relocate */
-	buf_page_t*	dpage)	/* in: free block to relocate to */
+	buf_page_t*	bpage,	/*!< in: block to relocate */
+	buf_page_t*	dpage)	/*!< in: free block to relocate to */
 {
 	buf_page_t*	b;
 
@@ -399,15 +397,15 @@ buf_buddy_relocate_block(
 }
 
 /**************************************************************************
-Try to relocate a block. */
+Try to relocate a block.
+@return	TRUE if relocated */
 static
 ibool
 buf_buddy_relocate(
 /*===============*/
-			/* out: TRUE if relocated */
-	void*	src,	/* in: block to relocate */
-	void*	dst,	/* in: free block to relocate to */
-	ulint	i)	/* in: index of buf_pool->zip_free[] */
+	void*	src,	/*!< in: block to relocate */
+	void*	dst,	/*!< in: free block to relocate to */
+	ulint	i)	/*!< in: index of buf_pool->zip_free[] */
 {
 	buf_page_t*	bpage;
 	const ulint	size	= BUF_BUDDY_LOW << i;
@@ -512,9 +510,9 @@ UNIV_INTERN
 void
 buf_buddy_free_low(
 /*===============*/
-	void*	buf,	/* in: block to be freed, must not be
+	void*	buf,	/*!< in: block to be freed, must not be
 			pointed to by the buffer pool */
-	ulint	i)	/* in: index of buf_pool->zip_free[],
+	ulint	i)	/*!< in: index of buf_pool->zip_free[],
 			or BUF_BUDDY_SIZES */
 {
 	buf_page_t*	bpage;

buf/buf0flu.c

@@ -45,25 +45,24 @@ Created 11/11/1995 Heikki Tuuri
 
 #if defined UNIV_DEBUG || defined UNIV_BUF_DEBUG
 /**********************************************************************
-Validates the flush list. */
+Validates the flush list.
+@return	TRUE if ok */
 static
 ibool
 buf_flush_validate_low(void);
 /*========================*/
-		/* out: TRUE if ok */
 #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. */
+on the basis of the <oldest_modification, space, offset> key.
+@return	pointer to the predecessor or NULL if no predecessor. */
 static
 buf_page_t*
 buf_flush_insert_in_flush_rbt(
 /*==========================*/
-				/* out: pointer to the predecessor or
-				NULL if no predecessor. */
-	buf_page_t*	bpage)	/* in: bpage to be inserted. */
+	buf_page_t*	bpage)	/*!< in: bpage to be inserted. */
 {
 	buf_page_t*		prev = NULL;
 	const ib_rbt_node_t*	c_node;
@@ -92,7 +91,7 @@ static
 void
 buf_flush_delete_from_flush_rbt(
 /*============================*/
-	buf_page_t*	bpage)	/* in: bpage to be removed. */
+	buf_page_t*	bpage)	/*!< in: bpage to be removed. */
 {
 
 	ibool	ret = FALSE;
@@ -110,17 +109,14 @@ This comparison is used to maintian ordering of blocks in the
 buf_pool->flush_rbt.
 Note that for the purpose of flush_rbt, we only need to order blocks
 on the oldest_modification. The other two fields are used to uniquely
-identify the blocks. */
+identify the blocks.
+@return	 < 0 if b2 < b1, 0 if b2 == b1, > 0 if b2 > b1 */
 static
 int
 buf_flush_block_cmp(
 /*================*/
-					/* out:
-					< 0 if b2 < b1,
-					0 if b2 == b1,
-					> 0 if b2 > b1 */
-	const void*	p1,		/* in: block1 */
-	const void*	p2)		/* in: block2 */
+	const void*	p1,		/*!< in: block1 */
+	const void*	p2)		/*!< in: block2 */
 {
 	int		ret;
 
@@ -195,7 +191,7 @@ UNIV_INTERN
 void
 buf_flush_insert_into_flush_list(
 /*=============================*/
-	buf_block_t*	block)	/* in/out: block which is modified */
+	buf_block_t*	block)	/*!< in/out: block which is modified */
 {
 	ut_ad(buf_pool_mutex_own());
 	ut_ad((UT_LIST_GET_FIRST(buf_pool->flush_list) == NULL)
@@ -230,7 +226,7 @@ UNIV_INTERN
 void
 buf_flush_insert_sorted_into_flush_list(
 /*====================================*/
-	buf_block_t*	block)	/* in/out: block which is modified */
+	buf_block_t*	block)	/*!< in/out: block which is modified */
 {
 	buf_page_t*	prev_b;
 	buf_page_t*	b;
@@ -282,13 +278,13 @@ buf_flush_insert_sorted_into_flush_list(
 
 /************************************************************************
 Returns TRUE if the file page block is immediately suitable for replacement,
-i.e., the transition FILE_PAGE => NOT_USED allowed. */
+i.e., the transition FILE_PAGE => NOT_USED allowed.
+@return	TRUE if can replace immediately */
 UNIV_INTERN
 ibool
 buf_flush_ready_for_replace(
 /*========================*/
-				/* out: TRUE if can replace immediately */
-	buf_page_t*	bpage)	/* in: buffer control block, must be
+	buf_page_t*	bpage)	/*!< in: buffer control block, must be
 				buf_page_in_file(bpage) and in the LRU list */
 {
 	ut_ad(buf_pool_mutex_own());
@@ -314,15 +310,15 @@ buf_flush_ready_for_replace(
 }
 
 /************************************************************************
-Returns TRUE if the block is modified and ready for flushing. */
+Returns TRUE if the block is modified and ready for flushing.
+@return	TRUE if can flush immediately */
 UNIV_INLINE
 ibool
 buf_flush_ready_for_flush(
 /*======================*/
-				/* out: TRUE if can flush immediately */
-	buf_page_t*	bpage,	/* in: buffer control block, must be
+	buf_page_t*	bpage,	/*!< in: buffer control block, must be
 				buf_page_in_file(bpage) */
-	enum buf_flush	flush_type)/* in: BUF_FLUSH_LRU or BUF_FLUSH_LIST */
+	enum buf_flush	flush_type)/*!< in: BUF_FLUSH_LRU or BUF_FLUSH_LIST */
 {
 	ut_a(buf_page_in_file(bpage));
 	ut_ad(buf_pool_mutex_own());
@@ -356,7 +352,7 @@ UNIV_INTERN
 void
 buf_flush_remove(
 /*=============*/
-	buf_page_t*	bpage)	/* in: pointer to the block in question */
+	buf_page_t*	bpage)	/*!< in: pointer to the block in question */
 {
 	ut_ad(buf_pool_mutex_own());
 	ut_ad(mutex_own(buf_page_get_mutex(bpage)));
@@ -405,8 +401,8 @@ UNIV_INTERN
 void
 buf_flush_relocate_on_flush_list(
 /*=============================*/
-	buf_page_t*	bpage,	/* in/out: control block being moved */
-	buf_page_t*	dpage)	/* in/out: destination block */
+	buf_page_t*	bpage,	/*!< in/out: control block being moved */
+	buf_page_t*	dpage)	/*!< in/out: destination block */
 {
 	buf_page_t* prev;
 	buf_page_t* prev_b = NULL;
@@ -460,7 +456,7 @@ UNIV_INTERN
 void
 buf_flush_write_complete(
 /*=====================*/
-	buf_page_t*	bpage)	/* in: pointer to the block in question */
+	buf_page_t*	bpage)	/*!< in: pointer to the block in question */
 {
 	enum buf_flush	flush_type;
 
@@ -747,7 +743,7 @@ static
 void
 buf_flush_post_to_doublewrite_buf(
 /*==============================*/
-	buf_page_t*	bpage)	/* in: buffer block to write */
+	buf_page_t*	bpage)	/*!< in: buffer block to write */
 {
 	ulint	zip_size;
 try_again:
@@ -805,9 +801,9 @@ UNIV_INTERN
 void
 buf_flush_init_for_writing(
 /*=======================*/
-	byte*		page,		/* in/out: page */
-	void*		page_zip_,	/* in/out: compressed page, or NULL */
-	ib_uint64_t	newest_lsn)	/* in: newest modification lsn
+	byte*		page,		/*!< in/out: page */
+	void*		page_zip_,	/*!< in/out: compressed page, or NULL */
+	ib_uint64_t	newest_lsn)	/*!< in: newest modification lsn
 					to the page */
 {
 	ut_ad(page);
@@ -886,7 +882,7 @@ static
 void
 buf_flush_write_block_low(
 /*======================*/
-	buf_page_t*	bpage)	/* in: buffer block to write */
+	buf_page_t*	bpage)	/*!< in: buffer block to write */
 {
 	ulint	zip_size	= buf_page_get_zip_size(bpage);
 	page_t*	frame		= NULL;
@@ -977,8 +973,8 @@ static
 void
 buf_flush_page(
 /*===========*/
-	buf_page_t*	bpage,		/* in: buffer control block */
-	enum buf_flush	flush_type)	/* in: BUF_FLUSH_LRU
+	buf_page_t*	bpage,		/*!< in: buffer control block */
+	enum buf_flush	flush_type)	/*!< in: BUF_FLUSH_LRU
 					or BUF_FLUSH_LIST */
 {
 	mutex_t*	block_mutex;
@@ -1081,15 +1077,15 @@ buf_flush_page(
 }
 
 /***************************************************************
-Flushes to disk all flushable pages within the flush area. */
+Flushes to disk all flushable pages within the flush area.
+@return	number of pages flushed */
 static
 ulint
 buf_flush_try_neighbors(
 /*====================*/
-					/* out: number of pages flushed */
-	ulint		space,		/* in: space id */
-	ulint		offset,		/* in: page offset */
-	enum buf_flush	flush_type)	/* in: BUF_FLUSH_LRU or
+	ulint		space,		/*!< in: space id */
+	ulint		offset,		/*!< in: page offset */
+	enum buf_flush	flush_type)	/*!< in: BUF_FLUSH_LRU or
 					BUF_FLUSH_LIST */
 {
 	buf_page_t*	bpage;
@@ -1176,23 +1172,20 @@ 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! */
+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 */
 UNIV_INTERN
 ulint
 buf_flush_batch(
 /*============*/
-					/* out: number of blocks for which the
-					write request was queued;
-					ULINT_UNDEFINED if there was a flush
-					of the same type already running */
-	enum buf_flush	flush_type,	/* in: BUF_FLUSH_LRU or
+	enum buf_flush	flush_type,	/*!< in: BUF_FLUSH_LRU or
 					BUF_FLUSH_LIST; if BUF_FLUSH_LIST,
 					then the caller must not own any
 					latches on pages */
-	ulint		min_n,		/* in: wished minimum mumber of blocks
+	ulint		min_n,		/*!< in: wished minimum mumber of blocks
 					flushed (it is not guaranteed that the
 					actual number is that big, though) */
-	ib_uint64_t	lsn_limit)	/* in the case BUF_FLUSH_LIST all
+	ib_uint64_t	lsn_limit)	/*!< in the case BUF_FLUSH_LIST all
 					blocks whose oldest_modification is
 					smaller than this should be flushed
 					(if their number does not exceed
@@ -1335,7 +1328,7 @@ UNIV_INTERN
 void
 buf_flush_wait_batch_end(
 /*=====================*/
-	enum buf_flush	type)	/* in: BUF_FLUSH_LRU or BUF_FLUSH_LIST */
+	enum buf_flush	type)	/*!< in: BUF_FLUSH_LRU or BUF_FLUSH_LIST */
 {
 	ut_ad((type == BUF_FLUSH_LRU) || (type == BUF_FLUSH_LIST));
 
@@ -1345,13 +1338,12 @@ buf_flush_wait_batch_end(
 /**********************************************************************
 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. */
+and in the free list.
+@return	number of blocks which should be flushed from the end of the LRU list */
 static
 ulint
 buf_flush_LRU_recommendation(void)
 /*==============================*/
-			/* out: number of blocks which should be flushed
-			from the end of the LRU list */
 {
 	buf_page_t*	bpage;
 	ulint		n_replaceable;
@@ -1423,12 +1415,12 @@ buf_flush_free_margin(void)
 
 #if defined UNIV_DEBUG || defined UNIV_BUF_DEBUG
 /**********************************************************************
-Validates the flush list. */
+Validates the flush list.
+@return	TRUE if ok */
 static
 ibool
 buf_flush_validate_low(void)
 /*========================*/
-		/* out: TRUE if ok */
 {
 	buf_page_t*		bpage;
 	const ib_rbt_node_t*	rnode = NULL;
@@ -1473,12 +1465,12 @@ buf_flush_validate_low(void)
 }
 
 /**********************************************************************
-Validates the flush list. */
+Validates the flush list.
+@return	TRUE if ok */
 UNIV_INTERN
 ibool
 buf_flush_validate(void)
 /*====================*/
-		/* out: TRUE if ok */
 {
 	ibool	ret;
 

buf/buf0rea.c

@@ -63,32 +63,28 @@ i/o-fixed buffer blocks */
 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. */
+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 */
 static
 ulint
 buf_read_page_low(
 /*==============*/
-			/* out: 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 */
-	ulint*	err,	/* out: DB_SUCCESS or DB_TABLESPACE_DELETED if we are
+	ulint*	err,	/*!< out: DB_SUCCESS or DB_TABLESPACE_DELETED if we are
 			trying to read from a non-existent tablespace, or a
 			tablespace which is just now being dropped */
-	ibool	sync,	/* in: TRUE if synchronous aio is desired */
-	ulint	mode,	/* in: BUF_READ_IBUF_PAGES_ONLY, ...,
+	ibool	sync,	/*!< in: TRUE if synchronous aio is desired */
+	ulint	mode,	/*!< in: BUF_READ_IBUF_PAGES_ONLY, ...,
 			ORed to OS_AIO_SIMULATED_WAKE_LATER (see below
 			at read-ahead functions) */
-	ulint	space,	/* in: space id */
-	ulint	zip_size,/* in: compressed page size, or 0 */
-	ibool	unzip,	/* in: TRUE=request uncompressed page */
-	ib_int64_t tablespace_version, /* in: if the space memory object has
+	ulint	space,	/*!< in: space id */
+	ulint	zip_size,/*!< in: compressed page size, or 0 */
+	ibool	unzip,	/*!< in: TRUE=request uncompressed page */
+	ib_int64_t tablespace_version, /*!< in: if the space memory object has
 			this timestamp different from what we are giving here,
 			treat the tablespace as dropped; this is a timestamp we
 			use to stop dangling page reads from a tablespace
 			which we have DISCARDed + IMPORTed back */
-	ulint	offset)	/* in: page number */
+	ulint	offset)	/*!< in: page number */
 {
 	buf_page_t*	bpage;
 	ulint		wake_later;
@@ -179,18 +175,15 @@ pages: to avoid deadlocks this function must be written such that it cannot
 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. */
+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! */
 static
 ulint
 buf_read_ahead_random(
 /*==================*/
-			/* out: 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! */
-	ulint	space,	/* in: space id */
-	ulint	zip_size,/* in: compressed page size in bytes, or 0 */
-	ulint	offset)	/* in: page number of a page which the current thread
+	ulint	space,	/*!< in: space id */
+	ulint	zip_size,/*!< in: compressed page size in bytes, or 0 */
+	ulint	offset)	/*!< in: page number of a page which the current thread
 			wants to access */
 {
 	ib_int64_t	tablespace_version;
@@ -332,16 +325,15 @@ 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. */
+sensible.
+@return	number of page read requests issued: this can be > 1 if read-ahead occurred */
 UNIV_INTERN
 ulint
 buf_read_page(
 /*==========*/
-			/* out: number of page read requests issued: this can
-			be > 1 if read-ahead occurred */
-	ulint	space,	/* in: space id */
-	ulint	zip_size,/* in: compressed page size in bytes, or 0 */
-	ulint	offset)	/* in: page number */
+	ulint	space,	/*!< in: space id */
+	ulint	zip_size,/*!< in: compressed page size in bytes, or 0 */
+	ulint	offset)	/*!< in: page number */
 {
 	ib_int64_t	tablespace_version;
 	ulint		count;
@@ -400,15 +392,15 @@ function must be written such that it cannot end up waiting for these
 latches!
 NOTE 3: 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 io. */
+which could result in a deadlock if the OS does not support asynchronous io.
+@return	number of page read requests issued */
 UNIV_INTERN
 ulint
 buf_read_ahead_linear(
 /*==================*/
-			/* out: number of page read requests issued */
-	ulint	space,	/* in: space id */
-	ulint	zip_size,/* in: compressed page size in bytes, or 0 */
-	ulint	offset)	/* in: page number of a page; NOTE: the current thread
+	ulint	space,	/*!< in: space id */
+	ulint	zip_size,/*!< in: compressed page size in bytes, or 0 */
+	ulint	offset)	/*!< in: page number of a page; NOTE: the current thread
 			must want access to this page (see NOTE 3 above) */
 {
 	ib_int64_t	tablespace_version;
@@ -653,24 +645,24 @@ UNIV_INTERN
 void
 buf_read_ibuf_merge_pages(
 /*======================*/
-	ibool		sync,		/* in: TRUE if the caller
+	ibool		sync,		/*!< in: TRUE if the caller
 					wants this function to wait
 					for the highest address page
 					to get read in, before this
 					function returns */
-	const ulint*	space_ids,	/* in: array of space ids */
-	const ib_int64_t* space_versions,/* in: the spaces must have
+	const ulint*	space_ids,	/*!< in: array of space ids */
+	const ib_int64_t* space_versions,/*!< in: the spaces must have
 					this version number
 					(timestamp), otherwise we
 					discard the read; we use this
 					to cancel reads if DISCARD +
 					IMPORT may have changed the
 					tablespace size */
-	const ulint*	page_nos,	/* in: array of page numbers
+	const ulint*	page_nos,	/*!< in: array of page numbers
 					to read, with the highest page
 					number the last in the
 					array */
-	ulint		n_stored)	/* in: number of elements
+	ulint		n_stored)	/*!< in: number of elements
 					in the arrays */
 {
 	ulint	i;
@@ -729,19 +721,19 @@ UNIV_INTERN
 void
 buf_read_recv_pages(
 /*================*/
-	ibool		sync,		/* in: TRUE if the caller
+	ibool		sync,		/*!< in: TRUE if the caller
 					wants this function to wait
 					for the highest address page
 					to get read in, before this
 					function returns */
-	ulint		space,		/* in: space id */
-	ulint		zip_size,	/* in: compressed page size in
+	ulint		space,		/*!< in: space id */
+	ulint		zip_size,	/*!< in: compressed page size in
 					bytes, or 0 */
-	const ulint*	page_nos,	/* in: array of page numbers
+	const ulint*	page_nos,	/*!< in: array of page numbers
 					to read, with the highest page
 					number the last in the
 					array */
-	ulint		n_stored)	/* in: number of page numbers
+	ulint		n_stored)	/*!< in: number of page numbers
 					in the array */
 {
 	ib_int64_t	tablespace_version;

data/data0data.c

@@ -52,15 +52,15 @@ UNIV_INTERN ulint	data_dummy;
 
 #ifndef UNIV_HOTBACKUP
 /*************************************************************************
-Tests if dfield data length and content is equal to the given. */
+Tests if dfield data length and content is equal to the given.
+@return	TRUE if equal */
 UNIV_INTERN
 ibool
 dfield_data_is_binary_equal(
 /*========================*/
-				/* out: TRUE if equal */
-	const dfield_t*	field,	/* in: field */
-	ulint		len,	/* in: data length or UNIV_SQL_NULL */
-	const byte*	data)	/* in: data */
+	const dfield_t*	field,	/*!< in: field */
+	ulint		len,	/*!< in: data length or UNIV_SQL_NULL */
+	const byte*	data)	/*!< in: data */
 {
 	if (len != dfield_get_len(field)) {
 
@@ -81,15 +81,14 @@ dfield_data_is_binary_equal(
 }
 
 /****************************************************************
-Compare two data tuples, respecting the collation of character fields. */
+Compare two data tuples, respecting the collation of character fields.
+@return	1, 0 , -1 if tuple1 is greater, equal, less, respectively, than tuple2 */
 UNIV_INTERN
 int
 dtuple_coll_cmp(
 /*============*/
-				/* out: 1, 0 , -1 if tuple1 is greater, equal,
-				less, respectively, than tuple2 */
-	const dtuple_t*	tuple1,	/* in: tuple 1 */
-	const dtuple_t*	tuple2)	/* in: tuple 2 */
+	const dtuple_t*	tuple1,	/*!< in: tuple 1 */
+	const dtuple_t*	tuple2)	/*!< in: tuple 2 */
 {
 	ulint	n_fields;
 	ulint	i;
@@ -129,8 +128,8 @@ UNIV_INTERN
 void
 dtuple_set_n_fields(
 /*================*/
-	dtuple_t*	tuple,		/* in: tuple */
-	ulint		n_fields)	/* in: number of fields */
+	dtuple_t*	tuple,		/*!< in: tuple */
+	ulint		n_fields)	/*!< in: number of fields */
 {
 	ut_ad(tuple);
 
@@ -139,13 +138,13 @@ dtuple_set_n_fields(
 }
 
 /**************************************************************
-Checks that a data field is typed. */
+Checks that a data field is typed.
+@return	TRUE if ok */
 static
 ibool
 dfield_check_typed_no_assert(
 /*=========================*/
-				/* out: TRUE if ok */
-	const dfield_t*	field)	/* in: data field */
+	const dfield_t*	field)	/*!< in: data field */
 {
 	if (dfield_get_type(field)->mtype > DATA_MYSQL
 	    || dfield_get_type(field)->mtype < DATA_VARCHAR) {
@@ -161,13 +160,13 @@ dfield_check_typed_no_assert(
 }
 
 /**************************************************************
-Checks that a data tuple is typed. */
+Checks that a data tuple is typed.
+@return	TRUE if ok */
 UNIV_INTERN
 ibool
 dtuple_check_typed_no_assert(
 /*=========================*/
-				/* out: TRUE if ok */
-	const dtuple_t*	tuple)	/* in: tuple */
+	const dtuple_t*	tuple)	/*!< in: tuple */
 {
 	const dfield_t*	field;
 	ulint		i;
@@ -199,13 +198,13 @@ dump:
 
 #ifdef UNIV_DEBUG
 /**************************************************************
-Checks that a data field is typed. Asserts an error if not. */
+Checks that a data field is typed. Asserts an error if not.
+@return	TRUE if ok */
 UNIV_INTERN
 ibool
 dfield_check_typed(
 /*===============*/
-				/* out: TRUE if ok */
-	const dfield_t*	field)	/* in: data field */
+	const dfield_t*	field)	/*!< in: data field */
 {
 	if (dfield_get_type(field)->mtype > DATA_MYSQL
 	    || dfield_get_type(field)->mtype < DATA_VARCHAR) {
@@ -222,13 +221,13 @@ dfield_check_typed(
 }
 
 /**************************************************************
-Checks that a data tuple is typed. Asserts an error if not. */
+Checks that a data tuple is typed. Asserts an error if not.
+@return	TRUE if ok */
 UNIV_INTERN
 ibool
 dtuple_check_typed(
 /*===============*/
-				/* out: TRUE if ok */
-	const dtuple_t*	tuple)	/* in: tuple */
+	const dtuple_t*	tuple)	/*!< in: tuple */
 {
 	const dfield_t*	field;
 	ulint		i;
@@ -245,13 +244,13 @@ dtuple_check_typed(
 
 /**************************************************************
 Validates the consistency of a tuple which must be complete, i.e,
-all fields must have been set. */
+all fields must have been set.
+@return	TRUE if ok */
 UNIV_INTERN
 ibool
 dtuple_validate(
 /*============*/
-				/* out: TRUE if ok */
-	const dtuple_t*	tuple)	/* in: tuple */
+	const dtuple_t*	tuple)	/*!< in: tuple */
 {
 	const dfield_t*	field;
 	ulint		n_fields;
@@ -302,7 +301,7 @@ UNIV_INTERN
 void
 dfield_print(
 /*=========*/
-	const dfield_t*	dfield)	/* in: dfield */
+	const dfield_t*	dfield)	/*!< in: dfield */
 {
 	const byte*	data;
 	ulint		len;
@@ -345,7 +344,7 @@ UNIV_INTERN
 void
 dfield_print_also_hex(
 /*==================*/
-	const dfield_t*	dfield)	/* in: dfield */
+	const dfield_t*	dfield)	/*!< in: dfield */
 {
 	const byte*	data;
 	ulint		len;
@@ -516,8 +515,8 @@ static
 void
 dfield_print_raw(
 /*=============*/
-	FILE*		f,		/* in: output stream */
-	const dfield_t*	dfield)		/* in: dfield */
+	FILE*		f,		/*!< in: output stream */
+	const dfield_t*	dfield)		/*!< in: dfield */
 {
 	ulint	len	= dfield_get_len(dfield);
 	if (!dfield_is_null(dfield)) {
@@ -539,8 +538,8 @@ UNIV_INTERN
 void
 dtuple_print(
 /*=========*/
-	FILE*		f,	/* in: output stream */
-	const dtuple_t*	tuple)	/* in: tuple */
+	FILE*		f,	/*!< in: output stream */
+	const dtuple_t*	tuple)	/*!< in: tuple */
 {
 	ulint		n_fields;
 	ulint		i;
@@ -565,19 +564,15 @@ dtuple_print(
 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. */
+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 */
 UNIV_INTERN
 big_rec_t*
 dtuple_convert_big_rec(
 /*===================*/
-				/* out, 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 */
-	dict_index_t*	index,	/* in: index */
-	dtuple_t*	entry,	/* in/out: index entry */
-	ulint*		n_ext)	/* in/out: number of
+	dict_index_t*	index,	/*!< in: index */
+	dtuple_t*	entry,	/*!< in/out: index entry */
+	ulint*		n_ext)	/*!< in/out: number of
 				externally stored columns */
 {
 	mem_heap_t*	heap;
@@ -732,9 +727,9 @@ UNIV_INTERN
 void
 dtuple_convert_back_big_rec(
 /*========================*/
-	dict_index_t*	index __attribute__((unused)),	/* in: index */
-	dtuple_t*	entry,	/* in: entry whose data was put to vector */
-	big_rec_t*	vector)	/* in, own: big rec vector; it is
+	dict_index_t*	index __attribute__((unused)),	/*!< in: index */
+	dtuple_t*	entry,	/*!< in: entry whose data was put to vector */
+	big_rec_t*	vector)	/*!< in, own: big rec vector; it is
 				freed in this function */
 {
 	big_rec_field_t*		b	= vector->fields;

data/data0type.c

@@ -41,23 +41,22 @@ 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. */
+the characters in the string occupy.
+@return	length of the prefix, in bytes */
 UNIV_INTERN
 ulint
 dtype_get_at_most_n_mbchars(
 /*========================*/
-					/* out: length of the prefix,
-					in bytes */
-	ulint		prtype,		/* in: precise type */
-	ulint		mbminlen,	/* in: minimum length of a
+	ulint		prtype,		/*!< in: precise type */
+	ulint		mbminlen,	/*!< in: minimum length of a
 					multi-byte character */
-	ulint		mbmaxlen,	/* in: maximum length of a
+	ulint		mbmaxlen,	/*!< in: maximum length of a
 					multi-byte character */
-	ulint		prefix_len,	/* in: length of the requested
+	ulint		prefix_len,	/*!< in: length of the requested
 					prefix, in characters, multiplied by
 					dtype_get_mbmaxlen(dtype) */
-	ulint		data_len,	/* in: length of str (in bytes) */
-	const char*	str)		/* in: the string whose prefix
+	ulint		data_len,	/*!< in: length of str (in bytes) */
+	const char*	str)		/*!< in: the string whose prefix
 					length is being determined */
 {
 	ut_a(data_len != UNIV_SQL_NULL);
@@ -82,13 +81,13 @@ dtype_get_at_most_n_mbchars(
 
 /*************************************************************************
 Checks if a data main type is a string type. Also a BLOB is considered a
-string type. */
+string type.
+@return	TRUE if string type */
 UNIV_INTERN
 ibool
 dtype_is_string_type(
 /*=================*/
-			/* out: TRUE if string type */
-	ulint	mtype)	/* in: InnoDB main data type code: DATA_CHAR, ... */
+	ulint	mtype)	/*!< in: InnoDB main data type code: DATA_CHAR, ... */
 {
 	if (mtype <= DATA_BLOB
 	    || mtype == DATA_MYSQL
@@ -103,14 +102,14 @@ dtype_is_string_type(
 /*************************************************************************
 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. */
+those DATA_BLOB columns this function currently returns FALSE.
+@return	TRUE if binary string type */
 UNIV_INTERN
 ibool
 dtype_is_binary_string_type(
 /*========================*/
-			/* out: TRUE if binary string type */
-	ulint	mtype,	/* in: main data type */
-	ulint	prtype)	/* in: precise type */
+	ulint	mtype,	/*!< in: main data type */
+	ulint	prtype)	/*!< in: precise type */
 {
 	if ((mtype == DATA_FIXBINARY)
 	    || (mtype == DATA_BINARY)
@@ -126,14 +125,14 @@ dtype_is_binary_string_type(
 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.
-For those DATA_BLOB columns this function currently returns TRUE. */
+For those DATA_BLOB columns this function currently returns TRUE.
+@return	TRUE if non-binary string type */
 UNIV_INTERN
 ibool
 dtype_is_non_binary_string_type(
 /*============================*/
-			/* out: TRUE if non-binary string type */
-	ulint	mtype,	/* in: main data type */
-	ulint	prtype)	/* in: precise type */
+	ulint	mtype,	/*!< in: main data type */
+	ulint	prtype)	/*!< in: precise type */
 {
 	if (dtype_is_string_type(mtype) == TRUE
 	    && dtype_is_binary_string_type(mtype, prtype) == FALSE) {
@@ -151,9 +150,9 @@ UNIV_INTERN
 ulint
 dtype_form_prtype(
 /*==============*/
-	ulint	old_prtype,	/* in: the MySQL type code and the flags
+	ulint	old_prtype,	/*!< in: the MySQL type code and the flags
 				DATA_BINARY_TYPE etc. */
-	ulint	charset_coll)	/* in: MySQL charset-collation code */
+	ulint	charset_coll)	/*!< in: MySQL charset-collation code */
 {
 	ut_a(old_prtype < 256 * 256);
 	ut_a(charset_coll < 256);
@@ -162,13 +161,13 @@ dtype_form_prtype(
 }
 
 /*************************************************************************
-Validates a data type structure. */
+Validates a data type structure.
+@return	TRUE if ok */
 UNIV_INTERN
 ibool
 dtype_validate(
 /*===========*/
-				/* out: TRUE if ok */
-	const dtype_t*	type)	/* in: type struct to validate */
+	const dtype_t*	type)	/*!< in: type struct to validate */
 {
 	ut_a(type);
 	ut_a(type->mtype >= DATA_VARCHAR);
@@ -192,7 +191,7 @@ UNIV_INTERN
 void
 dtype_print(
 /*========*/
-	const dtype_t*	type)	/* in: type */
+	const dtype_t*	type)	/*!< in: type */
 {
 	ulint	mtype;
 	ulint	prtype;

dict/dict0boot.c

@@ -40,14 +40,13 @@ Created 4/18/1996 Heikki Tuuri
 #include "os0file.h"
 
 /**************************************************************************
-Gets a pointer to the dictionary header and x-latches its page. */
+Gets a pointer to the dictionary header and x-latches its page.
+@return	pointer to the dictionary header, page x-latched */
 UNIV_INTERN
 dict_hdr_t*
 dict_hdr_get(
 /*=========*/
-			/* out: pointer to the dictionary header,
-			page x-latched */
-	mtr_t*	mtr)	/* in: mtr */
+	mtr_t*	mtr)	/*!< in: mtr */
 {
 	buf_block_t*	block;
 	dict_hdr_t*	header;
@@ -62,13 +61,13 @@ dict_hdr_get(
 }
 
 /**************************************************************************
-Returns a new table, index, or tree id. */
+Returns a new table, index, or tree id.
+@return	the new id */
 UNIV_INTERN
 dulint
 dict_hdr_get_new_id(
 /*================*/
-			/* out: the new id */
-	ulint	type)	/* in: DICT_HDR_ROW_ID, ... */
+	ulint	type)	/*!< in: DICT_HDR_ROW_ID, ... */
 {
 	dict_hdr_t*	dict_hdr;
 	dulint		id;
@@ -117,13 +116,13 @@ dict_hdr_flush_row_id(void)
 
 /*********************************************************************
 Creates the file page for the dictionary header. This function is
-called only at the database creation. */
+called only at the database creation.
+@return	TRUE if succeed */
 static
 ibool
 dict_hdr_create(
 /*============*/
-			/* out: TRUE if succeed */
-	mtr_t*	mtr)	/* in: mtr */
+	mtr_t*	mtr)	/*!< in: mtr */
 {
 	buf_block_t*	block;
 	dict_hdr_t*	dict_header;

dict/dict0load.c

@@ -41,16 +41,16 @@ Created 4/24/1996 Heikki Tuuri
 #include "srv0srv.h"
 
 /********************************************************************
-Returns TRUE if index's i'th column's name is 'name' .*/
+Returns TRUE if index's i'th column's name is 'name' .
+@return	 */
 static
 ibool
 name_of_col_is(
 /*===========*/
-				/* out: */
-	dict_table_t*	table,	/* in: table */
-	dict_index_t*	index,	/* in: index */
-	ulint		i,	/* in:  */
-	const char*	name)	/* in: name to compare to */
+	dict_table_t*	table,	/*!< in: table */
+	dict_index_t*	index,	/*!< in: index */
+	ulint		i,	/*!< in:  */
+	const char*	name)	/*!< in: name to compare to */
 {
 	ulint	tmp = dict_col_get_no(dict_field_get_col(
 					      dict_index_get_nth_field(
@@ -60,15 +60,13 @@ name_of_col_is(
 }
 
 /************************************************************************
-Finds the first table name in the given database. */
+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! */
 UNIV_INTERN
 char*
 dict_get_first_table_name_in_db(
 /*============================*/
-				/* out, own: table name, NULL if
-				does not exist; the caller must
-				free the memory in the string! */
-	const char*	name)	/* in: database name which ends in '/' */
+	const char*	name)	/*!< in: database name which ends in '/' */
 {
 	dict_table_t*	sys_tables;
 	btr_pcur_t	pcur;
@@ -237,15 +235,13 @@ loop:
 }
 
 /************************************************************************
-Determine the flags of a table described in SYS_TABLES. */
+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 */
 static
 ulint
 dict_sys_tables_get_flags(
 /*======================*/
-				/* out: compressed page size in kilobytes;
-				or 0 if the tablespace is uncompressed,
-				ULINT_UNDEFINED on error */
-	const rec_t*	rec)	/* in: a record of SYS_TABLES */
+	const rec_t*	rec)	/*!< in: a record of SYS_TABLES */
 {
 	const byte*	field;
 	ulint		len;
@@ -311,7 +307,7 @@ UNIV_INTERN
 void
 dict_check_tablespaces_and_store_max_id(
 /*====================================*/
-	ibool	in_crash_recovery)	/* in: are we doing a crash recovery */
+	ibool	in_crash_recovery)	/*!< in: are we doing a crash recovery */
 {
 	dict_table_t*	sys_tables;
 	dict_index_t*	sys_index;
@@ -427,8 +423,8 @@ static
 void
 dict_load_columns(
 /*==============*/
-	dict_table_t*	table,	/* in: table */
-	mem_heap_t*	heap)	/* in: memory heap for temporary storage */
+	dict_table_t*	table,	/*!< in: table */
+	mem_heap_t*	heap)	/*!< in: memory heap for temporary storage */
 {
 	dict_table_t*	sys_columns;
 	dict_index_t*	sys_index;
@@ -533,8 +529,8 @@ static
 void
 dict_load_fields(
 /*=============*/
-	dict_index_t*	index,	/* in: index whose fields to load */
-	mem_heap_t*	heap)	/* in: memory heap for temporary storage */
+	dict_index_t*	index,	/*!< in: index whose fields to load */
+	mem_heap_t*	heap)	/*!< in: memory heap for temporary storage */
 {
 	dict_table_t*	sys_fields;
 	dict_index_t*	sys_index;
@@ -630,17 +626,14 @@ next_rec:
 
 /************************************************************************
 Loads definitions for table indexes. Adds them to the data dictionary
-cache. */
+cache.
+@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(
 /*==============*/
-				/* out: DB_SUCCESS if ok, DB_CORRUPTION
-				if corruption of dictionary table or
-				DB_UNSUPPORTED if table has unknown index
-				type */
-	dict_table_t*	table,	/* in: table */
-	mem_heap_t*	heap)	/* in: memory heap for temporary storage */
+	dict_table_t*	table,	/*!< in: table */
+	mem_heap_t*	heap)	/*!< in: memory heap for temporary storage */
 {
 	dict_table_t*	sys_indexes;
 	dict_index_t*	sys_index;
@@ -808,17 +801,13 @@ 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. */
+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 */
 UNIV_INTERN
 dict_table_t*
 dict_load_table(
 /*============*/
-				/* out: 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 */
-	const char*	name)	/* in: table name in the
+	const char*	name)	/*!< in: table name in the
 				databasename/tablename format */
 {
 	ibool		ibd_file_missing	= FALSE;
@@ -999,13 +988,13 @@ err_exit:
 }
 
 /***************************************************************************
-Loads a table object based on the table id. */
+Loads a table object based on the table id.
+@return	table; NULL if table does not exist */
 UNIV_INTERN
 dict_table_t*
 dict_load_table_on_id(
 /*==================*/
-				/* out: table; NULL if table does not exist */
-	dulint	table_id)	/* in: table id */
+	dulint	table_id)	/*!< in: table id */
 {
 	byte		id_buf[8];
 	btr_pcur_t	pcur;
@@ -1097,7 +1086,7 @@ UNIV_INTERN
 void
 dict_load_sys_table(
 /*================*/
-	dict_table_t*	table)	/* in: system table */
+	dict_table_t*	table)	/*!< in: system table */
 {
 	mem_heap_t*	heap;
 
@@ -1116,9 +1105,9 @@ static
 void
 dict_load_foreign_cols(
 /*===================*/
-	const char*	id,	/* in: foreign constraint id as a
+	const char*	id,	/*!< in: foreign constraint id as a
 				null-terminated string */
-	dict_foreign_t*	foreign)/* in: foreign constraint object */
+	dict_foreign_t*	foreign)/*!< in: foreign constraint object */
 {
 	dict_table_t*	sys_foreign_cols;
 	dict_index_t*	sys_index;
@@ -1183,16 +1172,16 @@ dict_load_foreign_cols(
 }
 
 /***************************************************************************
-Loads a foreign key constraint to the dictionary cache. */
+Loads a foreign key constraint to the dictionary cache.
+@return	DB_SUCCESS or error code */
 static
 ulint
 dict_load_foreign(
 /*==============*/
-				/* out: DB_SUCCESS or error code */
-	const char*	id,	/* in: foreign constraint id as a
+	const char*	id,	/*!< in: foreign constraint id as a
 				null-terminated string */
 	ibool		check_charsets)
-				/* in: TRUE=check charset compatibility */
+				/*!< in: TRUE=check charset compatibility */
 {
 	dict_foreign_t*	foreign;
 	dict_table_t*	sys_foreign;
@@ -1312,14 +1301,14 @@ 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
 cache already contains all constraints where the other relevant table is
-already in the dictionary cache. */
+already in the dictionary cache.
+@return	DB_SUCCESS or error code */
 UNIV_INTERN
 ulint
 dict_load_foreigns(
 /*===============*/
-					/* out: DB_SUCCESS or error code */
-	const char*	table_name,	/* in: table name */
-	ibool		check_charsets)	/* in: TRUE=check charset
+	const char*	table_name,	/*!< in: table name */
+	ibool		check_charsets)	/*!< in: TRUE=check charset
 					compatibility */
 {
 	btr_pcur_t	pcur;

dict/dict0mem.c

@@ -40,19 +40,19 @@ Created 1/8/1996 Heikki Tuuri
 					creating a table or index object */
 
 /**************************************************************************
-Creates a table memory object. */
+Creates a table memory object.
+@return	own: table object */
 UNIV_INTERN
 dict_table_t*
 dict_mem_table_create(
 /*==================*/
-				/* out, own: table object */
-	const char*	name,	/* in: table name */
-	ulint		space,	/* in: space where the clustered index of
+	const char*	name,	/*!< in: table name */
+	ulint		space,	/*!< in: space where the clustered index of
 				the table is placed; this parameter is
 				ignored if the table is made a member of
 				a cluster */
-	ulint		n_cols,	/* in: number of columns */
-	ulint		flags)	/* in: table flags */
+	ulint		n_cols,	/*!< in: number of columns */
+	ulint		flags)	/*!< in: table flags */
 {
 	dict_table_t*	table;
 	mem_heap_t*	heap;
@@ -96,7 +96,7 @@ UNIV_INTERN
 void
 dict_mem_table_free(
 /*================*/
-	dict_table_t*	table)		/* in: table */
+	dict_table_t*	table)		/*!< in: table */
 {
 	ut_ad(table);
 	ut_ad(table->magic_n == DICT_TABLE_MAGIC_N);
@@ -107,17 +107,17 @@ dict_mem_table_free(
 }
 
 /********************************************************************
-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*
 dict_add_col_name(
 /*==============*/
-					/* out: new column names array */
-	const char*	col_names,	/* in: existing column names, or
+	const char*	col_names,	/*!< in: existing column names, or
 					NULL */
-	ulint		cols,		/* in: number of existing columns */
-	const char*	name,		/* in: new column name */
-	mem_heap_t*	heap)		/* in: heap */
+	ulint		cols,		/*!< in: number of existing columns */
+	const char*	name,		/*!< in: new column name */
+	mem_heap_t*	heap)		/*!< in: heap */
 {
 	ulint	old_len;
 	ulint	new_len;
@@ -160,12 +160,12 @@ UNIV_INTERN
 void
 dict_mem_table_add_col(
 /*===================*/
-	dict_table_t*	table,	/* in: table */
-	mem_heap_t*	heap,	/* in: temporary memory heap, or NULL */
-	const char*	name,	/* in: column name, or NULL */
-	ulint		mtype,	/* in: main datatype */
-	ulint		prtype,	/* in: precise type */
-	ulint		len)	/* in: precision */
+	dict_table_t*	table,	/*!< in: table */
+	mem_heap_t*	heap,	/*!< in: temporary memory heap, or NULL */
+	const char*	name,	/*!< in: column name, or NULL */
+	ulint		mtype,	/*!< in: main datatype */
+	ulint		prtype,	/*!< in: precise type */
+	ulint		len)	/*!< in: precision */
 {
 	dict_col_t*	col;
 #ifndef UNIV_HOTBACKUP
@@ -212,20 +212,20 @@ dict_mem_table_add_col(
 }
 
 /**************************************************************************
-Creates an index memory object. */
+Creates an index memory object.
+@return	own: index object */
 UNIV_INTERN
 dict_index_t*
 dict_mem_index_create(
 /*==================*/
-					/* out, own: index object */
-	const char*	table_name,	/* in: table name */
-	const char*	index_name,	/* in: index name */
-	ulint		space,		/* in: space where the index tree is
+	const char*	table_name,	/*!< in: table name */
+	const char*	index_name,	/*!< in: index name */
+	ulint		space,		/*!< in: space where the index tree is
 					placed, ignored if the index is of
 					the clustered type */
-	ulint		type,		/* in: DICT_UNIQUE,
+	ulint		type,		/*!< in: DICT_UNIQUE,
 					DICT_CLUSTERED, ... ORed */
-	ulint		n_fields)	/* in: number of fields */
+	ulint		n_fields)	/*!< in: number of fields */
 {
 	dict_index_t*	index;
 	mem_heap_t*	heap;
@@ -255,12 +255,12 @@ dict_mem_index_create(
 }
 
 /**************************************************************************
-Creates and initializes a foreign constraint memory object. */
+Creates and initializes a foreign constraint memory object.
+@return	own: foreign constraint struct */
 UNIV_INTERN
 dict_foreign_t*
 dict_mem_foreign_create(void)
 /*=========================*/
-				/* out, own: foreign constraint struct */
 {
 	dict_foreign_t*	foreign;
 	mem_heap_t*	heap;
@@ -282,9 +282,9 @@ UNIV_INTERN
 void
 dict_mem_index_add_field(
 /*=====================*/
-	dict_index_t*	index,		/* in: index */
-	const char*	name,		/* in: column name */
-	ulint		prefix_len)	/* in: 0 or the column prefix length
+	dict_index_t*	index,		/*!< in: index */
+	const char*	name,		/*!< in: column name */
+	ulint		prefix_len)	/*!< in: 0 or the column prefix length
 					in a MySQL index like
 					INDEX (textcol(25)) */
 {
@@ -307,7 +307,7 @@ UNIV_INTERN
 void
 dict_mem_index_free(
 /*================*/
-	dict_index_t*	index)	/* in: index */
+	dict_index_t*	index)	/*!< in: index */
 {
 	ut_ad(index);
 	ut_ad(index->magic_n == DICT_INDEX_MAGIC_N);

dyn/dyn0dyn.c

@@ -28,13 +28,13 @@ Created 2/5/1996 Heikki Tuuri
 #endif
 
 /****************************************************************
-Adds a new block to a dyn array. */
+Adds a new block to a dyn array.
+@return	created block */
 UNIV_INTERN
 dyn_block_t*
 dyn_array_add_block(
 /*================*/
-				/* out: created block */
-	dyn_array_t*	arr)	/* in: dyn array */
+	dyn_array_t*	arr)	/*!< in: dyn array */
 {
 	mem_heap_t*	heap;
 	dyn_block_t*	block;

ha/ha0storage.c

@@ -41,9 +41,9 @@ static
 const void*
 ha_storage_get(
 /*===========*/
-	ha_storage_t*	storage,	/* in: hash storage */
-	const void*	data,		/* in: data to check for */
-	ulint		data_len)	/* in: data length */
+	ha_storage_t*	storage,	/*!< in: hash storage */
+	const void*	data,		/*!< in: data to check for */
+	ulint		data_len)	/*!< in: data length */
 {
 	ha_storage_node_t*	node;
 	ulint			fold;
@@ -86,10 +86,10 @@ UNIV_INTERN
 const void*
 ha_storage_put_memlim(
 /*==================*/
-	ha_storage_t*	storage,	/* in/out: hash storage */
-	const void*	data,		/* in: data to store */
-	ulint		data_len,	/* in: data length */
-	ulint		memlim)		/* in: memory limit to obey */
+	ha_storage_t*	storage,	/*!< in/out: hash storage */
+	const void*	data,		/*!< in: data to store */
+	ulint		data_len,	/*!< in: data length */
+	ulint		memlim)		/*!< in: memory limit to obey */
 {
 	void*			raw;
 	ha_storage_node_t*	node;