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 @@ buf_buddy_alloc_low(
 }
 
 /**************************************************************************
-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;
 
@@ -397,15 +395,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;
@@ -510,9 +508,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,12 +45,12 @@ 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 */
 
 /************************************************************************
@@ -59,7 +59,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)
@@ -87,7 +87,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;
@@ -124,13 +124,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());
@@ -156,15 +156,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());
@@ -198,7 +198,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)));
@@ -237,7 +237,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;
 
@@ -524,7 +524,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:
@@ -582,9 +582,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);
@@ -663,7 +663,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;
@@ -754,8 +754,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;
@@ -858,15 +858,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;
@@ -953,23 +953,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
@@ -1112,7 +1109,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));
 
@@ -1122,13 +1119,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;
@@ -1200,12 +1196,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;
 
@@ -1229,12 +1225,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 @@ dtuple_check_typed_no_assert(
 
 #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;

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;

handler/ha_innodb.h

@@ -255,21 +255,21 @@ typedef struct trx_struct trx_t;
 /************************************************************************
 Converts an InnoDB error code to a MySQL error code and also tells to MySQL
 about a possible transaction rollback inside InnoDB caused by a lock wait
-timeout or a deadlock. */
+timeout or a deadlock.
+@return	MySQL error code */
 extern "C"
 int
 convert_error_code_to_mysql(
 /*========================*/
-				/* out: MySQL error code */
-	int		error,	/* in: InnoDB error code */
-	ulint		flags,	/* in: InnoDB table flags, or 0 */
-	MYSQL_THD	thd);	/* in: user thread handle or NULL */
+	int		error,	/*!< in: InnoDB error code */
+	ulint		flags,	/*!< in: InnoDB table flags, or 0 */
+	MYSQL_THD	thd);	/*!< in: user thread handle or NULL */
 
 /*************************************************************************
-Allocates an InnoDB transaction for a MySQL handler object. */
+Allocates an InnoDB transaction for a MySQL handler object.
+@return	InnoDB transaction handle */
 extern "C"
 trx_t*
 innobase_trx_allocate(
 /*==================*/
-				/* out: InnoDB transaction handle */
-	MYSQL_THD	thd);	/* in: user thread handle */
+	MYSQL_THD	thd);	/*!< in: user thread handle */

include/lock0priv.ic

@@ -32,13 +32,13 @@ methods but they are used only in that file. */
 #endif
 
 /*************************************************************************
-Gets the type of a lock. */
+Gets the type of a lock.
+@return	LOCK_TABLE or LOCK_REC */
 UNIV_INLINE
 ulint
 lock_get_type_low(
 /*==============*/
-				/* out: LOCK_TABLE or LOCK_REC */
-	const lock_t*	lock)	/* in: lock */
+	const lock_t*	lock)	/*!< in: lock */
 {
 	ut_ad(lock);