branches/zip: Add some Doxygen comments, mainly to structs, typedefs,

macros and global variables.  Many more to go.

btr/btr0sea.c

@@ -43,26 +43,29 @@ Created 2/17/1996 Heikki Tuuri
 #include "btr0btr.h"
 #include "ha0ha.h"
 
-/* Flag: has the search system been enabled?
+/** Flag: has the search system been enabled?
 Protected by btr_search_latch and btr_search_enabled_mutex. */
 UNIV_INTERN char		btr_search_enabled	= TRUE;
 
+/** Mutex protecting btr_search_enabled */
 static mutex_t			btr_search_enabled_mutex;
 
-/* A dummy variable to fool the compiler */
+/** A dummy variable to fool the compiler */
 UNIV_INTERN ulint		btr_search_this_is_zero = 0;
 
 #ifdef UNIV_SEARCH_PERF_STAT
+/** Number of successful adaptive hash index lookups */
 UNIV_INTERN ulint		btr_search_n_succ	= 0;
+/** Number of failed adaptive hash index lookups */
 UNIV_INTERN ulint		btr_search_n_hash_fail	= 0;
 #endif /* UNIV_SEARCH_PERF_STAT */
 
-/* padding to prevent other memory update
+/** padding to prevent other memory update
 hotspots from residing on the same memory
 cache line as btr_search_latch */
 UNIV_INTERN byte		btr_sea_pad1[64];
 
-/* The latch protecting the adaptive search system: this latch protects the
+/** The latch protecting the adaptive search system: this latch protects the
 (1) positions of records on those pages where a hash index has been built.
 NOTE: It does not protect values of non-ordering fields within a record from
 being updated in-place! We can use fact (1) to perform unique searches to
@@ -72,21 +75,20 @@ indexes. */
 same DRAM page as other hotspot semaphores */
 UNIV_INTERN rw_lock_t*		btr_search_latch_temp;
 
-/* padding to prevent other memory update hotspots from residing on
+/** padding to prevent other memory update hotspots from residing on
 the same memory cache line */
 UNIV_INTERN byte		btr_sea_pad2[64];
 
+/** The adaptive hash index */
 UNIV_INTERN btr_search_sys_t*	btr_search_sys;
 
-/* If the number of records on the page divided by this parameter
+/** If the number of records on the page divided by this parameter
 would have been successfully accessed using a hash index, the index
 is then built on the page, assuming the global limit has been reached */
-
 #define BTR_SEARCH_PAGE_BUILD_LIMIT	16
 
-/* The global limit for consecutive potentially successful hash searches,
+/** The global limit for consecutive potentially successful hash searches,
 before hash index building is started */
-
 #define BTR_SEARCH_BUILD_LIMIT		100
 
 /********************************************************************//**

data/data0data.c

@@ -41,12 +41,13 @@ Created 5/30/1994 Heikki Tuuri
 #endif /* !UNIV_HOTBACKUP */
 
 #ifdef UNIV_DEBUG
-/* data pointers of tuple fields are initialized to point here
-for error checking */
+/** Dummy variable to catch access to uninitialized fields.  In the
+debug version, dtuple_create() will make all fields of dtuple_t point
+to data_error. */
 UNIV_INTERN byte	data_error;
 
 # ifndef UNIV_DEBUG_VALGRIND
-/* this is used to fool the compiler in dtuple_validate */
+/** this is used to fool the compiler in dtuple_validate */
 UNIV_INTERN ulint	data_dummy;
 # endif /* !UNIV_DEBUG_VALGRIND */
 #endif /* UNIV_DEBUG */

include/btr0btr.h

@@ -35,41 +35,50 @@ Created 6/2/1994 Heikki Tuuri
 #include "btr0types.h"
 
 #ifndef UNIV_HOTBACKUP
-/* Maximum record size which can be stored on a page, without using the
+/** Maximum record size which can be stored on a page, without using the
 special big record storage structure */
-
 #define	BTR_PAGE_MAX_REC_SIZE	(UNIV_PAGE_SIZE / 2 - 200)
 
-/* Maximum depth of a B-tree in InnoDB. Note that this isn't a maximum as
-such; none of the tree operations avoid producing trees bigger than this. It
-is instead a "max depth that other code must work with", useful for e.g.
-fixed-size arrays that must store some information about each level in a
-tree. In other words: if a B-tree with bigger depth than this is
-encountered, it is not acceptable for it to lead to mysterious memory
-corruption, but it is acceptable for the program to die with a clear assert
-failure. */
+/** @brief Maximum depth of a B-tree in InnoDB.
+
+Note that this isn't a maximum as such; none of the tree operations
+avoid producing trees bigger than this. It is instead a "max depth
+that other code must work with", useful for e.g.  fixed-size arrays
+that must store some information about each level in a tree. In other
+words: if a B-tree with bigger depth than this is encountered, it is
+not acceptable for it to lead to mysterious memory corruption, but it
+is acceptable for the program to die with a clear assert failure. */
 #define BTR_MAX_LEVELS		100
 
-/* Latching modes for btr_cur_search_to_nth_level(). */
-#define BTR_SEARCH_LEAF		RW_S_LATCH
-#define BTR_MODIFY_LEAF		RW_X_LATCH
-#define BTR_NO_LATCHES		RW_NO_LATCH
-#define	BTR_MODIFY_TREE		33
-#define	BTR_CONT_MODIFY_TREE	34
-#define	BTR_SEARCH_PREV		35
-#define	BTR_MODIFY_PREV		36
+/** Latching modes for btr_cur_search_to_nth_level(). */
+enum btr_latch_mode {
+	/** Search a record on a leaf page and S-latch it. */
+	BTR_SEARCH_LEAF = RW_S_LATCH,
+	/** (Prepare to) modify a record on a leaf page and X-latch it. */
+	BTR_MODIFY_LEAF	= RW_X_LATCH,
+	/** Obtain no latches. */
+	BTR_NO_LATCHES = RW_NO_LATCH,
+	/** Start modifying the entire B-tree. */
+	BTR_MODIFY_TREE = 33,
+	/** Continue modifying the entire B-tree. */
+	BTR_CONT_MODIFY_TREE = 34,
+	/** Search the previous record. */
+	BTR_SEARCH_PREV = 35,
+	/** Modify the previous record. */
+	BTR_MODIFY_PREV = 36
+};
 
-/* If this is ORed to the latch mode, it means that the search tuple will be
-inserted to the index, at the searched position */
+/** If this is ORed to btr_latch_mode, it means that the search tuple
+will be inserted to the index, at the searched position */
 #define BTR_INSERT		512
 
-/* This flag ORed to latch mode says that we do the search in query
+/** This flag ORed to btr_latch_mode says that we do the search in query
 optimization */
 #define BTR_ESTIMATE		1024
 
-/* This flag ORed to latch mode says that we can ignore possible
-UNIQUE definition on secondary indexes when we decide if we can use the
-insert buffer to speed up inserts */
+/** This flag ORed to btr_latch_mode says that we can ignore possible
+UNIQUE definition on secondary indexes when we decide if we can use
+the insert buffer to speed up inserts */
 #define BTR_IGNORE_SEC_UNIQUE	2048
 
 /**************************************************************//**

include/btr0sea.h

@@ -182,74 +182,81 @@ ibool
 btr_search_validate(void);
 /*======================*/
 
-/* Flag: has the search system been enabled?
+/** Flag: has the search system been enabled?
 Protected by btr_search_latch and btr_search_enabled_mutex. */
 extern char btr_search_enabled;
 
-/* The search info struct in an index */
-
+/** The search info struct in an index */
 struct btr_search_struct{
-	ulint	ref_count;	/* Number of blocks in this index tree
+	ulint	ref_count;	/*!< Number of blocks in this index tree
 				that have search index built
 				i.e. block->index points to this index.
 				Protected by btr_search_latch except
 				when during initialization in
 				btr_search_info_create(). */
 
-	/* The following fields are not protected by any latch.
+	/* @{ The following fields are not protected by any latch.
 	Unfortunately, this means that they must be aligned to
 	the machine word, i.e., they cannot be turned into bit-fields. */
-	buf_block_t* root_guess;/* the root page frame when it was last time
+	buf_block_t* root_guess;/*!< the root page frame when it was last time
 				fetched, or NULL */
-	ulint	hash_analysis;	/* when this exceeds BTR_SEARCH_HASH_ANALYSIS,
-				the hash analysis starts; this is reset if no
+	ulint	hash_analysis;	/*!< when this exceeds
+				BTR_SEARCH_HASH_ANALYSIS, the hash
+				analysis starts; this is reset if no
 				success noticed */
-	ibool	last_hash_succ;	/* TRUE if the last search would have
+	ibool	last_hash_succ;	/*!< TRUE if the last search would have
 				succeeded, or did succeed, using the hash
 				index; NOTE that the value here is not exact:
 				it is not calculated for every search, and the
 				calculation itself is not always accurate! */
 	ulint	n_hash_potential;
-				/* number of consecutive searches
+				/*!< number of consecutive searches
 				which would have succeeded, or did succeed,
 				using the hash index;
 				the range is 0 .. BTR_SEARCH_BUILD_LIMIT + 5 */
-	/*----------------------*/
-	ulint	n_fields;	/* recommended prefix length for hash search:
+	/* @} */
+	/*---------------------- @{ */
+	ulint	n_fields;	/*!< recommended prefix length for hash search:
 				number of full fields */
-	ulint	n_bytes;	/* recommended prefix: number of bytes in
-				an incomplete field;
-				see also BTR_PAGE_MAX_REC_SIZE */
-	ibool	left_side;	/* TRUE or FALSE, depending on whether
+	ulint	n_bytes;	/*!< recommended prefix: number of bytes in
+				an incomplete field
+				@see BTR_PAGE_MAX_REC_SIZE */
+	ibool	left_side;	/*!< TRUE or FALSE, depending on whether
 				the leftmost record of several records with
 				the same prefix should be indexed in the
 				hash index */
-	/*----------------------*/
+	/*---------------------- @} */
 #ifdef UNIV_SEARCH_PERF_STAT
-	ulint	n_hash_succ;	/* number of successful hash searches thus
+	ulint	n_hash_succ;	/*!< number of successful hash searches thus
 				far */
-	ulint	n_hash_fail;	/* number of failed hash searches */
-	ulint	n_patt_succ;	/* number of successful pattern searches thus
+	ulint	n_hash_fail;	/*!< number of failed hash searches */
+	ulint	n_patt_succ;	/*!< number of successful pattern searches thus
 				far */
-	ulint	n_searches;	/* number of searches */
+	ulint	n_searches;	/*!< number of searches */
 #endif /* UNIV_SEARCH_PERF_STAT */
 #ifdef UNIV_DEBUG
-	ulint	magic_n;	/* magic number */
+	ulint	magic_n;	/*!< magic number @see BTR_SEARCH_MAGIC_N */
+/** value of btr_search_struct::magic_n, used in assertions */
 # define BTR_SEARCH_MAGIC_N	1112765
 #endif /* UNIV_DEBUG */
 };
 
-/* The hash index system */
-
+/** The hash index system */
 typedef struct btr_search_sys_struct	btr_search_sys_t;
 
+/** The hash index system */
 struct btr_search_sys_struct{
-	hash_table_t*	hash_index;
+	hash_table_t*	hash_index;	/*!< the adaptive hash index,
+					mapping dtuple_fold values
+					to rec_t pointers on index pages */
 };
 
+/** The adaptive hash index */
 extern btr_search_sys_t*	btr_search_sys;
 
-/* The latch protecting the adaptive search system: this latch protects the
+/** @brief The latch protecting the adaptive search system
+
+This latch protects the
 (1) hash index;
 (2) columns of a record to which we have a pointer in the hash index;
 
@@ -260,36 +267,34 @@ but does NOT protect:
 
 Bear in mind (3) and (4) when using the hash index.
 */
-
 extern rw_lock_t*	btr_search_latch_temp;
 
+/** The latch protecting the adaptive search system */
 #define btr_search_latch	(*btr_search_latch_temp)
 
 #ifdef UNIV_SEARCH_PERF_STAT
+/** Number of successful adaptive hash index lookups */
 extern ulint	btr_search_n_succ;
+/** Number of failed adaptive hash index lookups */
 extern ulint	btr_search_n_hash_fail;
 #endif /* UNIV_SEARCH_PERF_STAT */
 
-/* After change in n_fields or n_bytes in info, this many rounds are waited
+/** After change in n_fields or n_bytes in info, this many rounds are waited
 before starting the hash analysis again: this is to save CPU time when there
 is no hope in building a hash index. */
-
 #define BTR_SEARCH_HASH_ANALYSIS	17
 
-/* Limit of consecutive searches for trying a search shortcut on the search
+/** Limit of consecutive searches for trying a search shortcut on the search
 pattern */
-
 #define BTR_SEARCH_ON_PATTERN_LIMIT	3
 
-/* Limit of consecutive searches for trying a search shortcut using the hash
-index */
-
+/** Limit of consecutive searches for trying a search shortcut using
+the hash index */
 #define BTR_SEARCH_ON_HASH_LIMIT	3
 
-/* We do this many searches before trying to keep the search latch over calls
-from MySQL. If we notice someone waiting for the latch, we again set this
-much timeout. This is to reduce contention. */
-
+/** We do this many searches before trying to keep the search latch
+over calls from MySQL. If we notice someone waiting for the latch, we
+again set this much timeout. This is to reduce contention. */
 #define BTR_SEA_TIMEOUT			10000
 
 #ifndef UNIV_NONINL

include/buf0buf.h

@@ -64,23 +64,29 @@ extern buf_block_t*	back_block2;	/* second block, for page reorganize */
 /* Magic value to use instead of checksums when they are disabled */
 #define BUF_NO_CHECKSUM_MAGIC 0xDEADBEEFUL
 
-/* States of a control block (@see buf_page_struct).
+/** @brief States of a control block
+@see buf_page_struct
+
 The enumeration values must be 0..7. */
 enum buf_page_state {
-	BUF_BLOCK_ZIP_FREE = 0,		/* contains a free compressed page */
-	BUF_BLOCK_ZIP_PAGE,		/* contains a clean compressed page */
-	BUF_BLOCK_ZIP_DIRTY,		/* contains a compressed page that is
-					in the buf_pool->flush_list */
-
-	/* The constants for compressed-only pages must precede
-	BUF_BLOCK_NOT_USED; @see buf_block_state_valid() */
-
-	BUF_BLOCK_NOT_USED,		/* is in the free list */
-	BUF_BLOCK_READY_FOR_USE,	/* when buf_LRU_get_free_block returns
-					a block, it is in this state */
-	BUF_BLOCK_FILE_PAGE,		/* contains a buffered file page */
-	BUF_BLOCK_MEMORY,		/* contains some main memory object */
-	BUF_BLOCK_REMOVE_HASH		/* hash index should be removed
+	BUF_BLOCK_ZIP_FREE = 0,		/*!< contains a free
+					compressed page */
+	BUF_BLOCK_ZIP_PAGE,		/*!< contains a clean
+					compressed page */
+	BUF_BLOCK_ZIP_DIRTY,		/*!< contains a compressed
+					page that is in the
+					buf_pool->flush_list */
+
+	BUF_BLOCK_NOT_USED,		/*!< is in the free list;
+					must be after the BUF_BLOCK_ZIP_
+					constants for compressed-only pages
+					@see buf_block_state_valid() */
+	BUF_BLOCK_READY_FOR_USE,	/*!< when buf_LRU_get_free_block
+					returns a block, it is in this state */
+	BUF_BLOCK_FILE_PAGE,		/*!< contains a buffered file page */
+	BUF_BLOCK_MEMORY,		/*!< contains some main memory
+					object */
+	BUF_BLOCK_REMOVE_HASH		/*!< hash index should be removed
 					before putting to the free list */
 };
 
@@ -1241,7 +1247,9 @@ struct buf_block_struct{
 #endif /* !UNIV_HOTBACKUP */
 };
 
-/* Check if a buf_block_t object is in a valid state. */
+/** Check if a buf_block_t object is in a valid state
+@param block	buffer block
+@return		TRUE if valid */
 #define buf_block_state_valid(block)				\
 (buf_block_get_state(block) >= BUF_BLOCK_NOT_USED		\
  && (buf_block_get_state(block) <= BUF_BLOCK_REMOVE_HASH))

include/data0data.h

@@ -33,6 +33,8 @@ Created 5/30/1994 Heikki Tuuri
 #include "mem0mem.h"
 #include "dict0types.h"
 
+/** Storage for overflow data in a big record, that is, a clustered
+index record which needs external storage of data fields */
 typedef struct big_rec_struct		big_rec_t;
 
 #ifdef UNIV_DEBUG
@@ -422,53 +424,56 @@ dtuple_big_rec_free(
 
 /*######################################################################*/
 
-/* Structure for an SQL data field */
+/** Structure for an SQL data field */
 struct dfield_struct{
-	void*		data;	/* pointer to data */
-	unsigned	ext:1;	/* TRUE=externally stored, FALSE=local */
-	unsigned	len:32;	/* data length; UNIV_SQL_NULL if SQL null */
-	dtype_t		type;	/* type of data */
+	void*		data;	/*!< pointer to data */
+	unsigned	ext:1;	/*!< TRUE=externally stored, FALSE=local */
+	unsigned	len:32;	/*!< data length; UNIV_SQL_NULL if SQL null */
+	dtype_t		type;	/*!< type of data */
 };
 
+/** Structure for an SQL data tuple of fields (logical record) */
 struct dtuple_struct {
-	ulint		info_bits;	/* info bits of an index record:
+	ulint		info_bits;	/*!< info bits of an index record:
 					the default is 0; this field is used
 					if an index record is built from
 					a data tuple */
-	ulint		n_fields;	/* number of fields in dtuple */
-	ulint		n_fields_cmp;	/* number of fields which should
+	ulint		n_fields;	/*!< number of fields in dtuple */
+	ulint		n_fields_cmp;	/*!< number of fields which should
 					be used in comparison services
 					of rem0cmp.*; the index search
 					is performed by comparing only these
 					fields, others are ignored; the
 					default value in dtuple creation is
 					the same value as n_fields */
-	dfield_t*	fields;		/* fields */
+	dfield_t*	fields;		/*!< fields */
 	UT_LIST_NODE_T(dtuple_t) tuple_list;
-					/* data tuples can be linked into a
+					/*!< data tuples can be linked into a
 					list using this field */
 #ifdef UNIV_DEBUG
-	ulint		magic_n;
+	ulint		magic_n;	/*!< magic number, used in
+					debug assertions */
+/** Value of dtuple_struct::magic_n */
 # define		DATA_TUPLE_MAGIC_N	65478679
 #endif /* UNIV_DEBUG */
 };
 
-/* A slot for a field in a big rec vector */
-
+/** A slot for a field in a big rec vector */
 typedef struct big_rec_field_struct	big_rec_field_t;
+/** A slot for a field in a big rec vector */
 struct big_rec_field_struct {
-	ulint		field_no;	/* field number in record */
-	ulint		len;		/* stored data len */
-	const void*	data;		/* stored data */
+	ulint		field_no;	/*!< field number in record */
+	ulint		len;		/*!< stored data length, in bytes */
+	const void*	data;		/*!< stored data */
 };
 
-/* Storage format for overflow data in a big record, that is, a record
-which needs external storage of data fields */
-
+/** Storage format for overflow data in a big record, that is, a
+clustered index record which needs external storage of data fields */
 struct big_rec_struct {
-	mem_heap_t*	heap;		/* memory heap from which allocated */
-	ulint		n_fields;	/* number of stored fields */
-	big_rec_field_t* fields;	/* stored fields */
+	mem_heap_t*	heap;		/*!< memory heap from which
+					allocated */
+	ulint		n_fields;	/*!< number of stored fields */
+	big_rec_field_t*fields;		/*!< stored fields */
 };
 
 #ifndef UNIV_NONINL

include/data0data.ic

@@ -27,6 +27,9 @@ Created 5/30/1994 Heikki Tuuri
 #include "ut0rnd.h"
 
 #ifdef UNIV_DEBUG
+/** Dummy variable to catch access to uninitialized fields.  In the
+debug version, dtuple_create() will make all fields of dtuple_t point
+to data_error. */
 extern byte data_error;
 
 /*********************************************************************//**

include/ha0storage.h

@@ -72,23 +72,32 @@ ha_storage_put_memlim(
 	ulint		memlim);	/*!< in: memory limit to obey */
 
 /*******************************************************************//**
-Same as ha_storage_put_memlim() but without memory limit. */
-
+Same as ha_storage_put_memlim() but without memory limit.
+@param storage	in/out: hash storage
+@param data	in: data to store
+@param data_len	in: data length
+@return		pointer to the copy of the string */
 #define ha_storage_put(storage, data, data_len)	\
 	ha_storage_put_memlim((storage), (data), (data_len), 0)
 
 /*******************************************************************//**
 Copies string into the storage and returns a pointer to the copy. If the
 same string is already present, then pointer to it is returned.
-Strings are considered to be equal if strcmp(str1, str2) == 0. */
-
+Strings are considered to be equal if strcmp(str1, str2) == 0.
+@param storage	in/out: hash storage
+@param str	in: string to put
+@return		pointer to the copy of the string */
 #define ha_storage_put_str(storage, str)	\
 	((const char*) ha_storage_put((storage), (str), strlen(str) + 1))
 
 /*******************************************************************//**
 Copies string into the storage and returns a pointer to the copy obeying
-a memory limit. */
-
+a memory limit.
+If the same string is already present, then pointer to it is returned.
+Strings are considered to be equal if strcmp(str1, str2) == 0.
+@param storage	in/out: hash storage
+@param str	in: string to put
+@return		pointer to the copy of the string */
 #define ha_storage_put_str_memlim(storage, str, memlim)	\
 	((const char*) ha_storage_put_memlim((storage), (str),	\
 					     strlen(str) + 1, (memlim)))

include/ha0storage.ic

@@ -30,19 +30,21 @@ Created September 24, 2007 Vasil Dimov
 #include "hash0hash.h"
 #include "mem0mem.h"
 
+/** Hash storage for strings */
 struct ha_storage_struct {
-	mem_heap_t*	heap;	/* storage from which memory is
+	mem_heap_t*	heap;	/*!< memory heap from which memory is
 				allocated */
-	hash_table_t*	hash;	/* hash table used to avoid
+	hash_table_t*	hash;	/*!< hash table used to avoid
 				duplicates */
 };
 
-/* Objects of this type are put in the hash */
+/** Objects of this type are stored in ha_storage_t */
 typedef struct ha_storage_node_struct ha_storage_node_t;
+/** Objects of this type are stored in ha_storage_struct */
 struct ha_storage_node_struct {
-	ulint			data_len;/* length of the data */
-	const void*		data;	/* pointer to data */
-	ha_storage_node_t*	next;	/* next node in hash chain */
+	ulint			data_len;/*!< length of the data */
+	const void*		data;	/*!< pointer to data */
+	ha_storage_node_t*	next;	/*!< next node in hash chain */
 };
 
 /*******************************************************************//**

include/log0recv.ic

@@ -37,6 +37,7 @@ recv_recovery_is_on(void)
 }
 
 #ifdef UNIV_LOG_ARCHIVE
+/** TRUE when applying redo log records from an archived log file */
 extern ibool	recv_recovery_from_backup_on;
 
 /*******************************************************************//**

include/row0merge.h

@@ -39,25 +39,27 @@ Created 13/06/2005 Jan Lindstrom
 #include "row0mysql.h"
 #include "lock0types.h"
 
-/* This structure holds index field definitions */
-
+/** Index field definition */
 struct merge_index_field_struct {
-	ulint		prefix_len;	/* Prefix len */
-	const char*	field_name;	/* Field name */
+	ulint		prefix_len;	/*!< column prefix length, or 0
+					if indexing the whole column */
+	const char*	field_name;	/*!< field name */
 };
 
+/** Index field definition */
 typedef struct merge_index_field_struct merge_index_field_t;
 
-/* This structure holds index definitions */
-
+/** Definition of an index being created */
 struct merge_index_def_struct {
-	const char*		name;		/* Index name */
-	ulint			ind_type;	/* 0, DICT_UNIQUE,
+	const char*		name;		/*!< index name */
+	ulint			ind_type;	/*!< 0, DICT_UNIQUE,
 						or DICT_CLUSTERED */
-	ulint			n_fields;	/* Number of fields in index */
-	merge_index_field_t*	fields;		/* Field definitions */
+	ulint			n_fields;	/*!< number of fields
+						in index */
+	merge_index_field_t*	fields;		/*!< field definitions */
 };
 
+/** Definition of an index being created */
 typedef struct merge_index_def_struct merge_index_def_t;
 
 /*********************************************************************//**

include/ut0byte.h

@@ -29,21 +29,21 @@ Created 1/20/1994 Heikki Tuuri
 
 #include "univ.i"
 
-/* Type definition for a 64-bit unsigned integer, which works also
+/** Pair of ulint integers. */
+typedef	struct dulint_struct	dulint;
+/** Type definition for a 64-bit unsigned integer, which works also
 in 32-bit machines. NOTE! Access the fields only with the accessor
 functions. This definition appears here only for the compiler to
 know the size of a dulint. */
-
-typedef	struct dulint_struct	dulint;
 struct dulint_struct{
-	ulint	high;	/* most significant 32 bits */
-	ulint	low;	/* least significant 32 bits */
+	ulint	high;	/*!< most significant 32 bits */
+	ulint	low;	/*!< least significant 32 bits */
 };
 
-/* Zero value for a dulint */
+/** Zero value for a dulint */
 extern const dulint	ut_dulint_zero;
 
-/* Maximum value for a dulint */
+/** Maximum value for a dulint */
 extern const dulint	ut_dulint_max;
 
 /*******************************************************//**

include/ut0dbg.h

@@ -33,8 +33,8 @@ Created 1/30/1994 Heikki Tuuri
 #if defined(__GNUC__) && (__GNUC__ > 2)
 # define UT_DBG_FAIL(EXPR) UNIV_UNLIKELY(!((ulint)(EXPR)))
 #else
-extern ulint	ut_dbg_zero; /* This is used to eliminate
-				compiler warnings */
+/** This is used to eliminate compiler warnings */
+extern ulint	ut_dbg_zero;
 # define UT_DBG_FAIL(EXPR) !((ulint)(EXPR) + ut_dbg_zero)
 #endif
 
@@ -49,8 +49,9 @@ ut_dbg_assertion_failed(
 	ulint line);		/*!< in: line number of the assertion */
 
 #ifdef __NETWARE__
-/* Flag for ignoring further assertion failures.
-On NetWare, have a graceful exit rather than a segfault to avoid abends. */
+/** Flag for ignoring further assertion failures.  This is set to TRUE
+when on NetWare there happens an InnoDB assertion failure or other
+fatal error condition that requires an immediate shutdown. */
 extern ibool	panic_shutdown;
 /* Abort the execution. */
 void ut_dbg_panic(void);
@@ -65,13 +66,13 @@ void ut_dbg_panic(void);
 # endif
 
 # ifndef UT_DBG_USE_ABORT
-/* A null pointer that will be dereferenced to trigger a memory trap */
+/** A null pointer that will be dereferenced to trigger a memory trap */
 extern ulint*	ut_dbg_null_ptr;
 # endif
 
 # if defined(UNIV_SYNC_DEBUG) || !defined(UT_DBG_USE_ABORT)
-/* Flag for indicating that all threads should stop.  This will be set
-by ut_dbg_assertion_failed(). */
+/** If this is set to TRUE by ut_dbg_assertion_failed(), all threads
+will stop at the next ut_a() or ut_ad(). */
 extern ibool	ut_dbg_stop_threads;
 
 /*************************************************************//**

include/ut0mem.h

@@ -31,23 +31,41 @@ Created 5/30/1994 Heikki Tuuri
 #ifndef UNIV_HOTBACKUP
 # include "os0sync.h"
 
-/* The total amount of memory currently allocated from the operating
+/** The total amount of memory currently allocated from the operating
 system with os_mem_alloc_large() or malloc().  Does not count malloc()
 if srv_use_sys_malloc is set.  Protected by ut_list_mutex. */
 extern ulint		ut_total_allocated_memory;
 
-/* Mutex protecting ut_total_allocated_memory and ut_mem_block_list */
+/** Mutex protecting ut_total_allocated_memory and ut_mem_block_list */
 extern os_fast_mutex_t	ut_list_mutex;
 #endif /* !UNIV_HOTBACKUP */
 
+/** Wrapper for memcpy(3).  Copy memory area when the source and
+target are not overlapping.
+* @param dest	in: copy to
+* @param sour	in: copy from
+* @param n	in: number of bytes to copy
+* @return	dest */
 UNIV_INLINE
 void*
 ut_memcpy(void* dest, const void* sour, ulint n);
 
+/** Wrapper for memmove(3).  Copy memory area when the source and
+target are overlapping.
+* @param dest	in: copy to
+* @param sour	in: copy from
+* @param n	in: number of bytes to copy
+* @return	dest */
 UNIV_INLINE
 void*
 ut_memmove(void* dest, const void* sour, ulint n);
 
+/** Wrapper for memcmp(3).  Compare memory areas.
+* @param str1	in: first memory block to compare
+* @param str2	in: second memory block to compare
+* @param n	in: number of bytes to compare
+* @return	negative, 0, or positive if str1 is smaller, equal,
+		or greater than str2, respectively. */
 UNIV_INLINE
 int
 ut_memcmp(const void* str1, const void* str2, ulint n);
@@ -141,14 +159,26 @@ ut_free_all_mem(void);
 /*=================*/
 #endif /* !UNIV_HOTBACKUP */
 
+/** Wrapper for strcpy(3).  Copy a NUL-terminated string.
+* @param dest	in: copy to
+* @param sour	in: copy from
+* @return	dest */
 UNIV_INLINE
 char*
 ut_strcpy(char* dest, const char* sour);
 
+/** Wrapper for strlen(3).  Determine the length of a NUL-terminated string.
+* @param str	in: string
+* @return	length of the string in bytes, excluding the terminating NUL */
 UNIV_INLINE
 ulint
 ut_strlen(const char* str);
 
+/** Wrapper for strcmp(3).  Compare NUL-terminated strings.
+* @param str1	in: first string to compare
+* @param str2	in: second string to compare
+* @return	negative, 0, or positive if str1 is smaller, equal,
+		or greater than str2, respectively. */
 UNIV_INLINE
 int
 ut_strcmp(const char* str1, const char* str2);
@@ -239,10 +269,10 @@ ut_strreplace(
 	const char*	s2);	/*!< in: string to replace s1 with */
 
 /**********************************************************************//**
-Converts a raw binary data to a '\0'-terminated hex string. The output is
+Converts a raw binary data to a NUL-terminated hex string. The output is
 truncated if there is not enough space in "hex", make sure "hex_size" is at
 least (2 * raw_size + 1) if you do not want this to happen. Returns the
-actual number of characters written to "hex" (including the '\0').
+actual number of characters written to "hex" (including the NUL).
 @return	number of chars written */
 UNIV_INLINE
 ulint
@@ -256,7 +286,7 @@ ut_raw_to_hex(
 /*******************************************************************//**
 Adds single quotes to the start and end of string and escapes any quotes
 by doubling them. Returns the number of bytes that were written to "buf"
-(including the terminating '\0'). If buf_size is too small then the
+(including the terminating NUL). If buf_size is too small then the
 trailing bytes from "str" are discarded.
 @return	number of bytes that were written */
 UNIV_INLINE

include/ut0mem.ic

@@ -26,6 +26,12 @@ Created 5/30/1994 Heikki Tuuri
 #include "ut0byte.h"
 #include "mach0data.h"
 
+/** Wrapper for memcpy(3).  Copy memory area when the source and
+target are not overlapping.
+* @param dest	in: copy to
+* @param sour	in: copy from
+* @param n	in: number of bytes to copy
+* @return	dest */
 UNIV_INLINE
 void*
 ut_memcpy(void* dest, const void* sour, ulint n)
@@ -33,6 +39,12 @@ ut_memcpy(void* dest, const void* sour, ulint n)
 	return(memcpy(dest, sour, n));
 }
 
+/** Wrapper for memmove(3).  Copy memory area when the source and
+target are overlapping.
+* @param dest	in: copy to
+* @param sour	in: copy from
+* @param n	in: number of bytes to copy
+* @return	dest */
 UNIV_INLINE
 void*
 ut_memmove(void* dest, const void* sour, ulint n)
@@ -40,6 +52,12 @@ ut_memmove(void* dest, const void* sour, ulint n)
 	return(memmove(dest, sour, n));
 }
 
+/** Wrapper for memcmp(3).  Compare memory areas.
+* @param str1	in: first memory block to compare
+* @param str2	in: second memory block to compare
+* @param n	in: number of bytes to compare
+* @return	negative, 0, or positive if str1 is smaller, equal,
+		or greater than str2, respectively. */
 UNIV_INLINE
 int
 ut_memcmp(const void* str1, const void* str2, ulint n)
@@ -47,6 +65,10 @@ ut_memcmp(const void* str1, const void* str2, ulint n)
 	return(memcmp(str1, str2, n));
 }
 
+/** Wrapper for strcpy(3).  Copy a NUL-terminated string.
+* @param dest	in: copy to
+* @param sour	in: copy from
+* @return	dest */
 UNIV_INLINE
 char*
 ut_strcpy(char* dest, const char* sour)
@@ -54,6 +76,9 @@ ut_strcpy(char* dest, const char* sour)
 	return(strcpy(dest, sour));
 }
 
+/** Wrapper for strlen(3).  Determine the length of a NUL-terminated string.
+* @param str	in: string
+* @return	length of the string in bytes, excluding the terminating NUL */
 UNIV_INLINE
 ulint
 ut_strlen(const char* str)
@@ -61,6 +86,11 @@ ut_strlen(const char* str)
 	return(strlen(str));
 }
 
+/** Wrapper for strcmp(3).  Compare NUL-terminated strings.
+* @param str1	in: first string to compare
+* @param str2	in: second string to compare
+* @return	negative, 0, or positive if str1 is smaller, equal,
+		or greater than str2, respectively. */
 UNIV_INLINE
 int
 ut_strcmp(const char* str1, const char* str2)
@@ -90,10 +120,10 @@ ut_strlenq(
 }
 
 /**********************************************************************//**
-Converts a raw binary data to a '\0'-terminated hex string. The output is
+Converts a raw binary data to a NUL-terminated hex string. The output is
 truncated if there is not enough space in "hex", make sure "hex_size" is at
 least (2 * raw_size + 1) if you do not want this to happen. Returns the
-actual number of characters written to "hex" (including the '\0').
+actual number of characters written to "hex" (including the NUL).
 @return	number of chars written */
 UNIV_INLINE
 ulint
@@ -212,7 +242,7 @@ ut_raw_to_hex(
 /*******************************************************************//**
 Adds single quotes to the start and end of string and escapes any quotes
 by doubling them. Returns the number of bytes that were written to "buf"
-(including the terminating '\0'). If buf_size is too small then the
+(including the terminating NUL). If buf_size is too small then the
 trailing bytes from "str" are discarded.
 @return	number of bytes that were written */
 UNIV_INLINE

include/ut0rnd.ic

@@ -35,6 +35,7 @@ Created 5/30/1994 Heikki Tuuri
 #define UT_XOR_RND1		187678878
 #define UT_XOR_RND2		143537923
 
+/** Seed value of ut_rnd_gen_ulint() */
 extern	ulint	 ut_rnd_ulint_counter;
 
 /********************************************************//**

include/ut0ut.h

@@ -37,12 +37,14 @@ Created 1/20/1994 Heikki Tuuri
 /** Index name prefix in fast index creation, as a string constant */
 #define TEMP_INDEX_PREFIX_STR	"\377"
 
+/** Time stamp */
 typedef time_t	ib_time_t;
 
 /*********************************************************************//**
 Delays execution for at most max_wait_us microseconds or returns earlier
-if cond becomes true; cond is evaluated every 2 ms. */
-
+if cond becomes true.
+@param cond		in: condition to wait for; evaluated every 2 ms
+@param max_wait_us	in: maximum delay to wait, in microseconds */
 #define UT_WAIT_FOR(cond, max_wait_us)				\
 do {								\
 	ullint	start_us;					\
@@ -115,19 +117,34 @@ ut_pair_cmp(
 	ulint	b1,	/*!< in: more significant part of second pair */
 	ulint	b2);	/*!< in: less significant part of second pair */
 /*************************************************************//**
-Determines if a number is zero or a power of two. */
+Determines if a number is zero or a power of two.
+@param n	in: number
+@return		nonzero if n is zero or a power of two; zero otherwise */
 #define ut_is_2pow(n) UNIV_LIKELY(!((n) & ((n) - 1)))
 /*************************************************************//**
-Calculates fast the remainder of n/m when m is a power of two. */
+Calculates fast the remainder of n/m when m is a power of two.
+@param n	in: numerator
+@param m	in: denominator, must be a power of two
+@return		the remainder of n/m */
 #define ut_2pow_remainder(n, m) ((n) & ((m) - 1))
 /*************************************************************//**
 Calculates the biggest multiple of m that is not bigger than n
-when m is a power of two.  In other words, rounds n down to m * k. */
+when m is a power of two.  In other words, rounds n down to m * k.
+@param n	in: number to round down
+@param m	in: alignment, must be a power of two
+@return		n rounded down to the biggest possible integer multiple of m */
 #define ut_2pow_round(n, m) ((n) & ~((m) - 1))
+/** Align a number down to a multiple of a power of two.
+@param n	in: number to round down
+@param m	in: alignment, must be a power of two
+@return		n rounded down to the biggest possible integer multiple of m */
 #define ut_calc_align_down(n, m) ut_2pow_round(n, m)
 /********************************************************//**
 Calculates the smallest multiple of m that is not smaller than n
-when m is a power of two.  In other words, rounds n up to m * k. */
+when m is a power of two.  In other words, rounds n up to m * k.
+@param n	in: number to round up
+@param m	in: alignment, must be a power of two
+@return		n rounded up to the smallest possible integer multiple of m */
 #define ut_calc_align(n, m) (((n) + ((m) - 1)) & ~((m) - 1))
 /*************************************************************//**
 Calculates fast the 2-logarithm of a number, rounded upward to an
@@ -156,8 +173,10 @@ ut_2_power_up(
 	ulint	n)	/*!< in: number != 0 */
 	__attribute__((const));
 
-/* Determine how many bytes (groups of 8 bits) are needed to
-store the given number of bits. */
+/** Determine how many bytes (groups of 8 bits) are needed to
+store the given number of bits.
+@param b	in: bits
+@return		number of bytes (octets) needed to represent b */
 #define UT_BITS_IN_BYTES(b) (((b) + 7) / 8)
 
 /**********************************************************//**

include/ut0vec.h

@@ -29,6 +29,7 @@ Created 4/6/2006 Osku Salerma
 #include "univ.i"
 #include "mem0mem.h"
 
+/** An automatically resizing vector data type. */
 typedef struct ib_vector_struct ib_vector_t;
 
 /* An automatically resizing vector datatype with the following properties:
@@ -109,12 +110,12 @@ ib_vector_free(
 /*===========*/
 	ib_vector_t*	vec);	/*!< in,own: vector */
 
-/* See comment at beginning of file. */
+/** An automatically resizing vector data type. */
 struct ib_vector_struct {
-	mem_heap_t*	heap;	/* heap */
-	void**		data;	/* data elements */
-	ulint		used;	/* number of elements currently used */
-	ulint		total;	/* number of elements allocated */
+	mem_heap_t*	heap;	/*!< heap */
+	void**		data;	/*!< data elements */
+	ulint		used;	/*!< number of elements currently used */
+	ulint		total;	/*!< number of elements allocated */
 };
 
 #ifndef UNIV_NONINL

log/log0recv.c

@@ -51,31 +51,40 @@ Created 9/20/1997 Heikki Tuuri
 # include "sync0sync.h"
 #else /* !UNIV_HOTBACKUP */
 
-/* This is set to FALSE if the backup was originally taken with the
+/** This is set to FALSE if the backup was originally taken with the
 ibbackup --include regexp option: then we do not want to create tables in
 directories which were not included */
 UNIV_INTERN ibool	recv_replay_file_ops	= TRUE;
 #endif /* !UNIV_HOTBACKUP */
 
-/* Log records are stored in the hash table in chunks at most of this size;
+/** Log records are stored in the hash table in chunks at most of this size;
 this must be less than UNIV_PAGE_SIZE as it is stored in the buffer pool */
 #define RECV_DATA_BLOCK_SIZE	(MEM_MAX_ALLOC_IN_BUF - sizeof(recv_data_t))
 
-/* Read-ahead area in applying log records to file pages */
+/** Read-ahead area in applying log records to file pages */
 #define RECV_READ_AHEAD_AREA	32
 
+/** The recovery system */
 UNIV_INTERN recv_sys_t*	recv_sys = NULL;
+/** TRUE when applying redo log records during crash recovery; FALSE
+otherwise.  Note that this is FALSE while a background thread is
+rolling back incomplete transactions. */
 UNIV_INTERN ibool	recv_recovery_on = FALSE;
 #ifdef UNIV_LOG_ARCHIVE
+/** TRUE when applying redo log records from an archived log file */
 UNIV_INTERN ibool	recv_recovery_from_backup_on = FALSE;
 #endif /* UNIV_LOG_ARCHIVE */
 
 #ifndef UNIV_HOTBACKUP
+/** TRUE when recv_init_crash_recovery() has been called. */
 UNIV_INTERN ibool	recv_needed_recovery = FALSE;
 
+/** TRUE if buf_page_is_corrupted() should check if the log sequence
+number (FIL_PAGE_LSN) is in the future.  Initially FALSE, and set by
+recv_recovery_from_checkpoint_start_func(). */
 UNIV_INTERN ibool	recv_lsn_checks_on = FALSE;
 
-/* There are two conditions under which we scan the logs, the first
+/** There are two conditions under which we scan the logs, the first
 is normal startup and the second is when we do a recovery from an
 archive.
 This flag is set if we are doing a scan from the last checkpoint during
@@ -83,48 +92,53 @@ startup. If we find log entries that were written after the last checkpoint
 we know that the server was not cleanly shutdown. We must then initialize
 the crash recovery environment before attempting to store these entries in
 the log hash table. */
-UNIV_INTERN ibool	recv_log_scan_is_startup_type = FALSE;
+static ibool		recv_log_scan_is_startup_type = FALSE;
 
-/* If the following is TRUE, the buffer pool file pages must be invalidated
+/** If the following is TRUE, the buffer pool file pages must be invalidated
 after recovery and no ibuf operations are allowed; this becomes TRUE if
 the log record hash table becomes too full, and log records must be merged
 to file pages already before the recovery is finished: in this case no
 ibuf operations are allowed, as they could modify the pages read in the
-buffer pool before the pages have been recovered to the up-to-date state */
-
-/* Recovery is running and no operations on the log files are allowed
-yet: the variable name is misleading */
+buffer pool before the pages have been recovered to the up-to-date state.
 
+TRUE means that recovery is running and no operations on the log files
+are allowed yet: the variable name is misleading. */
 UNIV_INTERN ibool	recv_no_ibuf_operations = FALSE;
+/** TRUE when the redo log is being backed up */
 # define recv_is_making_a_backup		FALSE
+/** TRUE when recovering from a backed up redo log file */
 # define recv_is_from_backup			FALSE
 #else /* !UNIV_HOTBACKUP */
 # define recv_needed_recovery			FALSE
+/** TRUE when the redo log is being backed up */
 UNIV_INTERN ibool	recv_is_making_a_backup = FALSE;
+/** TRUE when recovering from a backed up redo log file */
 UNIV_INTERN ibool	recv_is_from_backup	= FALSE;
 # define buf_pool_get_curr_size() (5 * 1024 * 1024)
 #endif /* !UNIV_HOTBACKUP */
-/* The following counter is used to decide when to print info on
+/** The following counter is used to decide when to print info on
 log scan */
-UNIV_INTERN ulint	recv_scan_print_counter	= 0;
+static ulint	recv_scan_print_counter	= 0;
 
-UNIV_INTERN ulint	recv_previous_parsed_rec_type	= 999999;
-UNIV_INTERN ulint	recv_previous_parsed_rec_offset	= 0;
-UNIV_INTERN ulint	recv_previous_parsed_rec_is_multi = 0;
+/** The type of the previous parsed redo log record */
+static ulint	recv_previous_parsed_rec_type	= 999999;
+/** The offset of the previous parsed redo log record */
+static ulint	recv_previous_parsed_rec_offset	= 0;
+/** The 'multi' flag of the previous parsed redo log record */
+static ulint	recv_previous_parsed_rec_is_multi = 0;
 
+/** Maximum page number encountered in the redo log */
 UNIV_INTERN ulint	recv_max_parsed_page_no		= 0;
 
-/* This many frames must be left free in the buffer pool when we scan
+/** This many frames must be left free in the buffer pool when we scan
 the log and store the scanned log records in the buffer pool: we will
 use these free frames to read in pages when we start applying the
 log records to the database. */
-
 UNIV_INTERN ulint	recv_n_pool_free_frames		= 256;
 
-/* The maximum lsn we see for a page during the recovery process. If this
+/** The maximum lsn we see for a page during the recovery process. If this
 is bigger than the lsn we are able to scan up to, that is an indication that
 the recovery failed and the database may be corrupt. */
-
 UNIV_INTERN ib_uint64_t	recv_max_page_lsn;
 
 /* prototypes */
@@ -1307,10 +1321,10 @@ recv_recover_page_func(
 /*===================*/
 #ifndef UNIV_HOTBACKUP
 	ibool		just_read_in,
-				/*!< in: TRUE if the i/o-handler calls this for
-				a freshly read page */
+				/*!< in: TRUE if the i/o handler calls
+				this for a freshly read page */
 #endif /* !UNIV_HOTBACKUP */
-	buf_block_t*	block)	/*!< in: buffer block */
+	buf_block_t*	block)	/*!< in/out: buffer block */
 {
 	page_t*		page;
 	recv_addr_t*	recv_addr;
@@ -2680,7 +2694,8 @@ ulint
 recv_recovery_from_checkpoint_start_func(
 /*=====================================*/
 #ifdef UNIV_LOG_ARCHIVE
-	ulint		type,		/*!< in: LOG_CHECKPOINT or LOG_ARCHIVE */
+	ulint		type,		/*!< in: LOG_CHECKPOINT or
+					LOG_ARCHIVE */
 	ib_uint64_t	limit_lsn,	/*!< in: recover up to this lsn
 					if possible */
 #endif /* UNIV_LOG_ARCHIVE */
@@ -2705,10 +2720,14 @@ recv_recovery_from_checkpoint_start_func(
 
 #ifdef UNIV_LOG_ARCHIVE
 	ut_ad(type != LOG_CHECKPOINT || limit_lsn == IB_ULONGLONG_MAX);
+/** TRUE when recovering from a checkpoint */
 # define TYPE_CHECKPOINT	(type == LOG_CHECKPOINT)
+/** Recover up to this log sequence number */
 # define LIMIT_LSN		limit_lsn
 #else /* UNIV_LOG_ARCHIVE */
+/** TRUE when recovering from a checkpoint */
 # define TYPE_CHECKPOINT	1
+/** Recover up to this log sequence number */
 # define LIMIT_LSN		IB_ULONGLONG_MAX
 #endif /* UNIV_LOG_ARCHIVE */
 

row/row0merge.c

@@ -58,57 +58,62 @@ Completed by Sunny Bains and Marko Makela
 #include "handler0alter.h"
 
 #ifdef UNIV_DEBUG
-/* Set these in order ot enable debug printout. */
+/** Set these in order ot enable debug printout. */
+/* @{ */
 static ibool	row_merge_print_cmp;
 static ibool	row_merge_print_read;
 static ibool	row_merge_print_write;
+/* @} */
 #endif /* UNIV_DEBUG */
 
-/* Block size for I/O operations in merge sort.  The minimum is
-UNIV_PAGE_SIZE, or page_get_free_space_of_empty() rounded to a power of 2.
+/** @brief Block size for I/O operations in merge sort.
+
+The minimum is UNIV_PAGE_SIZE, or page_get_free_space_of_empty()
+rounded to a power of 2.
 
 When not creating a PRIMARY KEY that contains column prefixes, this
 can be set as small as UNIV_PAGE_SIZE / 2.  See the comment above
 ut_ad(data_size < sizeof(row_merge_block_t)). */
-
 typedef byte	row_merge_block_t[1048576];
 
-/* Secondary buffer for I/O operations of merge records.  This buffer
-is used for writing or reading a record that spans two row_merge_block_t.
-Thus, it must be able to hold one merge record, whose maximum size is
-the same as the minimum size of row_merge_block_t. */
+/** @brief Secondary buffer for I/O operations of merge records.
 
+This buffer is used for writing or reading a record that spans two
+row_merge_block_t.  Thus, it must be able to hold one merge record,
+whose maximum size is the same as the minimum size of
+row_merge_block_t. */
 typedef byte	mrec_buf_t[UNIV_PAGE_SIZE];
 
-/* Merge record in row_merge_block_t.  The format is the same as a
-record in ROW_FORMAT=COMPACT with the exception that the
-REC_N_NEW_EXTRA_BYTES are omitted. */
+/** @brief Merge record in row_merge_block_t.
+
+The format is the same as a record in ROW_FORMAT=COMPACT with the
+exception that the REC_N_NEW_EXTRA_BYTES are omitted. */
 typedef byte	mrec_t;
 
-/* Buffer for sorting in main memory. */
+/** Buffer for sorting in main memory. */
 struct row_merge_buf_struct {
-	mem_heap_t*	heap;		/* memory heap where allocated */
-	dict_index_t*	index;		/* the index the tuples belong to */
-	ulint		total_size;	/* total amount of data bytes */
-	ulint		n_tuples;	/* number of data tuples */
-	ulint		max_tuples;	/* maximum number of data tuples */
-	const dfield_t**tuples;		/* array of pointers to
+	mem_heap_t*	heap;		/*!< memory heap where allocated */
+	dict_index_t*	index;		/*!< the index the tuples belong to */
+	ulint		total_size;	/*!< total amount of data bytes */
+	ulint		n_tuples;	/*!< number of data tuples */
+	ulint		max_tuples;	/*!< maximum number of data tuples */
+	const dfield_t**tuples;		/*!< array of pointers to
 					arrays of fields that form
 					the data tuples */
-	const dfield_t**tmp_tuples;	/* temporary copy of tuples,
+	const dfield_t**tmp_tuples;	/*!< temporary copy of tuples,
 					for sorting */
 };
 
+/** Buffer for sorting in main memory. */
 typedef struct row_merge_buf_struct row_merge_buf_t;
 
-/* Information about temporary files used in merge sort are stored
-to this structure */
-
+/** Information about temporary files used in merge sort */
 struct merge_file_struct {
-	int	fd;		/* File descriptor */
-	ulint	offset;		/* File offset */
+	int	fd;		/*!< file descriptor */
+	ulint	offset;		/*!< file offset */
 };
 
+/** Information about temporary files used in merge sort */
 typedef struct merge_file_struct merge_file_t;
 
 #ifdef UNIV_DEBUG
@@ -389,13 +394,14 @@ row_merge_buf_add(
 	return(TRUE);
 }
 
-/* Structure for reporting duplicate records. */
+/** Structure for reporting duplicate records. */
 struct row_merge_dup_struct {
-	const dict_index_t*	index;		/* index being sorted */
-	TABLE*			table;		/* MySQL table object */
-	ulint			n_dup;		/* number of duplicates */
+	const dict_index_t*	index;		/*!< index being sorted */
+	TABLE*			table;		/*!< MySQL table object */
+	ulint			n_dup;		/*!< number of duplicates */
 };
 
+/** Structure for reporting duplicate records. */
 typedef struct row_merge_dup_struct row_merge_dup_t;
 
 /*************************************************************//**
@@ -498,8 +504,19 @@ row_merge_tuple_sort(
 	ulint			high)	/*!< in: upper bound of the
 					sorting area, exclusive */
 {
+/** Wrapper for row_merge_tuple_sort() to inject some more context to
+UT_SORT_FUNCTION_BODY().
+@param a	array of tuples that being sorted
+@param b	aux (work area), same size as tuples[]
+@param c	lower bound of the sorting area, inclusive
+@param d	upper bound of the sorting area, inclusive */
 #define row_merge_tuple_sort_ctx(a,b,c,d) \
 	row_merge_tuple_sort(n_field, dup, a, b, c, d)
+/** Wrapper for row_merge_tuple_cmp() to inject some more context to
+UT_SORT_FUNCTION_BODY().
+@param a	first tuple to be compared
+@param b	second tuple to be compared
+@return	1, 0, -1 if a is greater, equal, less, respectively, than b */
 #define row_merge_tuple_cmp_ctx(a,b) row_merge_tuple_cmp(n_field, a, b, dup)
 
 	UT_SORT_FUNCTION_BODY(row_merge_tuple_sort_ctx,
@@ -1323,6 +1340,10 @@ row_merge_blocks(
 
 	/* Write a record and read the next record.  Split the output
 	file in two halves, which can be merged on the following pass. */
+
+/** Write a record via buffer 2 and read the next record to buffer N.
+@param N	number of the buffer (0 or 1)
+@param AT_END	statement to execute at end of input */
 #define ROW_MERGE_WRITE_GET_NEXT(N, AT_END)				\
 	do {								\
 		b2 = row_merge_write_rec(&block[2], &buf[2], b2,	\

row/row0mysql.c

@@ -52,30 +52,43 @@ Created 9/17/2000 Heikki Tuuri
 #include "fil0fil.h"
 #include "ibuf0ibuf.h"
 
-/* Provide optional 4.x backwards compatibility for 5.0 and above */
+/** Provide optional 4.x backwards compatibility for 5.0 and above */
 UNIV_INTERN ibool	row_rollback_on_timeout	= FALSE;
 
-/* List of tables we should drop in background. ALTER TABLE in MySQL requires
-that the table handler can drop the table in background when there are no
-queries to it any more. Protected by the kernel mutex. */
+/** Chain node of the list of tables to drop in the background. */
 typedef struct row_mysql_drop_struct	row_mysql_drop_t;
+
+/** Chain node of the list of tables to drop in the background. */
 struct row_mysql_drop_struct{
-	char*				table_name;
-	UT_LIST_NODE_T(row_mysql_drop_t) row_mysql_drop_list;
+	char*				table_name;	/*!< table name */
+	UT_LIST_NODE_T(row_mysql_drop_t)row_mysql_drop_list;
+							/*!< list chain node */
 };
 
+/** @brief List of tables we should drop in background.
+
+ALTER TABLE in MySQL requires that the table handler can drop the
+table in background when there are no queries to it any
+more.  Protected by kernel_mutex. */
 static UT_LIST_BASE_NODE_T(row_mysql_drop_t)	row_mysql_drop_list;
+/** Flag: has row_mysql_drop_list been initialized? */
 static ibool	row_mysql_drop_list_inited	= FALSE;
 
-/* Magic table names for invoking various monitor threads */
+/** Magic table names for invoking various monitor threads */
+/* @{ */
 static const char S_innodb_monitor[] = "innodb_monitor";
 static const char S_innodb_lock_monitor[] = "innodb_lock_monitor";
 static const char S_innodb_tablespace_monitor[] = "innodb_tablespace_monitor";
 static const char S_innodb_table_monitor[] = "innodb_table_monitor";
 static const char S_innodb_mem_validate[] = "innodb_mem_validate";
-
-/* Evaluates to true if str1 equals str2_onstack, used for comparing
-the above strings. */
+/* @} */
+
+/** Evaluates to true if str1 equals str2_onstack, used for comparing
+the magic table names.
+@param str1		in: string to compare
+@param str1_len 	in: length of str1, in bytes, including terminating NUL
+@param str2_onstack	in: char[] array containing a NUL terminated string
+@return			TRUE if str1 equals str2_onstack */
 #define STR_EQ(str1, str1_len, str2_onstack) \
 	((str1_len) == sizeof(str2_onstack) \
 	 && memcmp(str1, str2_onstack, sizeof(str2_onstack)) == 0)
@@ -3379,7 +3392,7 @@ drop_all_foreign_keys_in_db(
 
 	pars_info_add_str_literal(pinfo, "dbname", name);
 
-/* true if for_name is not prefixed with dbname */
+/** true if for_name is not prefixed with dbname */
 #define TABLE_NOT_IN_THIS_DB \
 "SUBSTR(for_name, 0, LENGTH(:dbname)) <> :dbname"
 

trx/trx0i_s.c

@@ -54,15 +54,17 @@ Created July 17, 2007 Vasil Dimov
 #include "ut0mem.h"
 #include "ut0ut.h"
 
+/** Initial number of rows in the table cache */
 #define TABLE_CACHE_INITIAL_ROWSNUM	1024
 
-/* Table cache's rows are stored in a set of chunks. When a new row is
-added a new chunk is allocated if necessary. MEM_CHUNKS_IN_TABLE_CACHE
-specifies the maximum number of chunks.
-Assuming that the first one is 1024 rows (TABLE_CACHE_INITIAL_ROWSNUM)
-and each subsequent is N/2 where N is the number of rows we have
-allocated till now, then 39th chunk would have 1677416425 number of rows
-and all chunks would have 3354832851 number of rows. */
+/** @brief The maximum number of chunks to allocate for a table cache.
+
+The rows of a table cache are stored in a set of chunks. When a new
+row is added a new chunk is allocated if necessary.  Assuming that the
+first one is 1024 rows (TABLE_CACHE_INITIAL_ROWSNUM) and each
+subsequent is N/2 where N is the number of rows we have allocated till
+now, then 39th chunk would accommodate 1677416425 rows and all chunks
+would accommodate 3354832851 rows. */
 #define MEM_CHUNKS_IN_TABLE_CACHE	39
 
 /* The following are some testing auxiliary macros. Do not enable them
@@ -113,62 +115,67 @@ noop because it will be empty. */
 	 - (cache)->mem_allocd			\
 	 - ha_storage_get_size((cache)->storage))
 
-/* Memory for each table in the intermediate buffer is allocated in
+/** Memory for each table in the intermediate buffer is allocated in
 separate chunks. These chunks are considered to be concatenated to
 represent one flat array of rows. */
 typedef struct i_s_mem_chunk_struct {
-	ulint	offset;		/* offset, in number of rows */
-	ulint	rows_allocd;	/* the size of this chunk, in number
+	ulint	offset;		/*!< offset, in number of rows */
+	ulint	rows_allocd;	/*!< the size of this chunk, in number
 				of rows */
-	void*	base;		/* start of the chunk */
+	void*	base;		/*!< start of the chunk */
 } i_s_mem_chunk_t;
 
-/* This represents one table's cache. */
+/** This represents one table's cache. */
 typedef struct i_s_table_cache_struct {
-	ulint		rows_used;	/* number of used rows */
-	ulint		rows_allocd;	/* number of allocated rows */
-	ulint		row_size;	/* size of a single row */
-	i_s_mem_chunk_t	chunks[MEM_CHUNKS_IN_TABLE_CACHE]; /* array of
+	ulint		rows_used;	/*!< number of used rows */
+	ulint		rows_allocd;	/*!< number of allocated rows */
+	ulint		row_size;	/*!< size of a single row */
+	i_s_mem_chunk_t	chunks[MEM_CHUNKS_IN_TABLE_CACHE]; /*!< array of
 					memory chunks that stores the
 					rows */
 } i_s_table_cache_t;
 
-/* This structure describes the intermediate buffer */
+/** This structure describes the intermediate buffer */
 struct trx_i_s_cache_struct {
-	rw_lock_t	rw_lock;	/* read-write lock protecting
+	rw_lock_t	rw_lock;	/*!< read-write lock protecting
 					the rest of this structure */
-	ullint		last_read;	/* last time the cache was read;
+	ullint		last_read;	/*!< last time the cache was read;
 					measured in microseconds since
 					epoch */
-	mutex_t		last_read_mutex;/* mutex protecting the
+	mutex_t		last_read_mutex;/*!< mutex protecting the
 					last_read member - it is updated
 					inside a shared lock of the
 					rw_lock member */
-	i_s_table_cache_t innodb_trx;	/* innodb_trx table */
-	i_s_table_cache_t innodb_locks;	/* innodb_locks table */
-	i_s_table_cache_t innodb_lock_waits;/* innodb_lock_waits table */
-/* the hash table size is LOCKS_HASH_CELLS_NUM * sizeof(void*) bytes */
+	i_s_table_cache_t innodb_trx;	/*!< innodb_trx table */
+	i_s_table_cache_t innodb_locks;	/*!< innodb_locks table */
+	i_s_table_cache_t innodb_lock_waits;/*!< innodb_lock_waits table */
+/** the hash table size is LOCKS_HASH_CELLS_NUM * sizeof(void*) bytes */
 #define LOCKS_HASH_CELLS_NUM		10000
-	hash_table_t*	locks_hash;	/* hash table used to eliminate
+	hash_table_t*	locks_hash;	/*!< hash table used to eliminate
 					duplicate entries in the
 					innodb_locks table */
+/** Initial size of the cache storage */
 #define CACHE_STORAGE_INITIAL_SIZE	1024
+/** Number of hash cells in the cache storage */
 #define CACHE_STORAGE_HASH_CELLS	2048
-	ha_storage_t*	storage;	/* storage for external volatile
+	ha_storage_t*	storage;	/*!< storage for external volatile
 					data that can possibly not be
 					available later, when we release
 					the kernel mutex */
-	ulint		mem_allocd;	/* the amount of memory
+	ulint		mem_allocd;	/*!< the amount of memory
 					allocated with mem_alloc*() */
-	ibool		is_truncated;	/* this is TRUE if the memory
+	ibool		is_truncated;	/*!< this is TRUE if the memory
 					limit was hit and thus the data
 					in the cache is truncated */
 };
 
-/* This is the intermediate buffer where data needed to fill the
+/** This is the intermediate buffer where data needed to fill the
 INFORMATION SCHEMA tables is fetched and later retrieved by the C++
 code in handler/i_s.cc. */
 static trx_i_s_cache_t	trx_i_s_cache_static;
+/** This is the intermediate buffer where data needed to fill the
+INFORMATION SCHEMA tables is fetched and later retrieved by the C++
+code in handler/i_s.cc. */
 UNIV_INTERN trx_i_s_cache_t*	trx_i_s_cache = &trx_i_s_cache_static;
 
 /*******************************************************************//**

ut/ut0byte.c

@@ -29,10 +29,10 @@ Created 5/11/1994 Heikki Tuuri
 #include "ut0byte.ic"
 #endif
 
-/* Zero value for a dulint */
+/** Zero value for a dulint */
 UNIV_INTERN const dulint	ut_dulint_zero	= {0, 0};
 
-/* Maximum value for a dulint */
+/** Maximum value for a dulint */
 UNIV_INTERN const dulint	ut_dulint_max	= {0xFFFFFFFFUL, 0xFFFFFFFFUL};
 
 #ifdef notdefined /* unused code */

ut/ut0dbg.c

@@ -28,22 +28,22 @@ Created 1/30/1994 Heikki Tuuri
 
 #if defined(__GNUC__) && (__GNUC__ > 2)
 #else
-/* This is used to eliminate compiler warnings */
+/** This is used to eliminate compiler warnings */
 UNIV_INTERN ulint	ut_dbg_zero	= 0;
 #endif
 
 #if defined(UNIV_SYNC_DEBUG) || !defined(UT_DBG_USE_ABORT)
-/* If this is set to TRUE all threads will stop into the next assertion
-and assert */
+/** If this is set to TRUE by ut_dbg_assertion_failed(), all threads
+will stop at the next ut_a() or ut_ad(). */
 UNIV_INTERN ibool	ut_dbg_stop_threads	= FALSE;
 #endif
 #ifdef __NETWARE__
-/* This is set to TRUE when on NetWare there happens an InnoDB
-assertion failure or other fatal error condition that requires an
-immediate shutdown. */
+/** Flag for ignoring further assertion failures.  This is set to TRUE
+when on NetWare there happens an InnoDB assertion failure or other
+fatal error condition that requires an immediate shutdown. */
 UNIV_INTERN ibool panic_shutdown = FALSE;
 #elif !defined(UT_DBG_USE_ABORT)
-/* Null pointer used to generate memory trap */
+/** A null pointer that will be dereferenced to trigger a memory trap */
 UNIV_INTERN ulint*	ut_dbg_null_ptr		= NULL;
 #endif
 

ut/ut0mem.c

@@ -35,32 +35,38 @@ Created 5/11/1994 Heikki Tuuri
 
 #include <stdlib.h>
 
-/* This struct is placed first in every allocated memory block */
+/** This struct is placed first in every allocated memory block */
 typedef struct ut_mem_block_struct ut_mem_block_t;
 
-/* The total amount of memory currently allocated from the operating
+/** The total amount of memory currently allocated from the operating
 system with os_mem_alloc_large() or malloc().  Does not count malloc()
 if srv_use_sys_malloc is set.  Protected by ut_list_mutex. */
 UNIV_INTERN ulint		ut_total_allocated_memory	= 0;
 
-/* Mutex protecting ut_total_allocated_memory and ut_mem_block_list */
+/** Mutex protecting ut_total_allocated_memory and ut_mem_block_list */
 UNIV_INTERN os_fast_mutex_t	ut_list_mutex;
 
+/** Dynamically allocated memory block */
 struct ut_mem_block_struct{
 	UT_LIST_NODE_T(ut_mem_block_t) mem_block_list;
-			/* mem block list node */
-	ulint	size;	/* size of allocated memory */
-	ulint	magic_n;
+			/*!< mem block list node */
+	ulint	size;	/*!< size of allocated memory */
+	ulint	magic_n;/*!< magic number (UT_MEM_MAGIC_N) */
 };
 
+/** The value of ut_mem_block_struct::magic_n.  Used in detecting
+memory corruption. */
 #define UT_MEM_MAGIC_N	1601650166
 
-/* List of all memory blocks allocated from the operating system
+/** List of all memory blocks allocated from the operating system
 with malloc.  Protected by ut_list_mutex. */
 static UT_LIST_BASE_NODE_T(ut_mem_block_t)   ut_mem_block_list;
 
+/** Flag: has ut_mem_block_list been initialized? */
 static ibool  ut_mem_block_list_inited = FALSE;
 
+/** A dummy pointer for generating a null pointer exception in
+ut_malloc_low() */
 static ulint*	ut_mem_null_ptr	= NULL;
 
 /**********************************************************************//**

ut/ut0rnd.c

@@ -29,12 +29,14 @@ Created 5/11/1994 Heikki Tuuri
 #include "ut0rnd.ic"
 #endif
 
-/* These random numbers are used in ut_find_prime */
+/** These random numbers are used in ut_find_prime */
+/*@{*/
 #define	UT_RANDOM_1	1.0412321
 #define	UT_RANDOM_2	1.1131347
 #define UT_RANDOM_3	1.0132677
+/*@}*/
 
-
+/** Seed value of ut_rnd_gen_ulint(). */
 UNIV_INTERN ulint	ut_rnd_ulint_counter = 65654363;
 
 /***********************************************************//**

ut/ut0ut.c

@@ -39,6 +39,7 @@ Created 5/11/1994 Heikki Tuuri
 # include "mysql_com.h" /* NAME_LEN */
 #endif /* UNIV_HOTBACKUP */
 
+/** A constant to prevent the compiler from optimizing ut_delay() away. */
 UNIV_INTERN ibool	ut_always_false	= FALSE;
 
 #ifdef __WIN__
@@ -87,6 +88,8 @@ ut_gettimeofday(
 	return(0);
 }
 #else
+/** An alias for gettimeofday(2).  On Microsoft Windows, we have to
+reimplement this function. */
 #define	ut_gettimeofday		gettimeofday
 #endif