branches/zip: Add missing function comments.

handler/ha_innodb.cc

@@ -1113,19 +1113,22 @@ innobase_mysql_tmpfile(void)
 #endif /* defined (__WIN__) && defined (MYSQL_DYNAMIC_PLUGIN) */
 
 /*************************************************************************
-Wrapper around MySQL's copy_and_convert function, see it for
-documentation. */
+Wrapper around MySQL's copy_and_convert function. */
 extern "C" UNIV_INTERN
 ulint
 innobase_convert_string(
 /*====================*/
-	void*		to,
-	ulint		to_length,
-	CHARSET_INFO*	to_cs,
-	const void*	from,
-	ulint		from_length,
-	CHARSET_INFO*	from_cs,
-	uint*		errors)
+					/* out: number of bytes copied
+					to 'to' */
+	void*		to,		/* out: converted string */
+	ulint		to_length,	/* in: number of bytes reserved
+					for the converted string */
+	CHARSET_INFO*	to_cs,		/* in: character set to convert to */
+	const void*	from,		/* in: string to convert */
+	ulint		from_length,	/* in: number of bytes to convert */
+	CHARSET_INFO*	from_cs,	/* in: character set to convert from */
+	uint*		errors)		/* out: number of errors encountered
+					during the conversion */
 {
   return(copy_and_convert((char*)to, (uint32) to_length, to_cs,
                           (const char*)from, (uint32) from_length, from_cs,

include/data0type.h

@@ -255,14 +255,16 @@ UNIV_INLINE
 ulint
 dtype_get_mtype(
 /*============*/
-	const dtype_t*	type);
+				/* out: SQL main data type */
+	const dtype_t*	type);	/* in: data type */
 /*************************************************************************
 Gets the precise data type. */
 UNIV_INLINE
 ulint
 dtype_get_prtype(
 /*=============*/
-	const dtype_t*	type);
+				/* out: precise data type */
+	const dtype_t*	type);	/* in: data type */
 #ifndef UNIV_HOTBACKUP
 /*************************************************************************
 Compute the mbminlen and mbmaxlen members of a data type structure. */
@@ -310,7 +312,9 @@ UNIV_INLINE
 ulint
 dtype_get_len(
 /*==========*/
-	const dtype_t*	type);
+				/* out: fixed length of the type, in bytes,
+				or 0 if variable-length */
+	const dtype_t*	type);	/* in: data type */
 #ifndef UNIV_HOTBACKUP
 /*************************************************************************
 Gets the minimum length of a character, in bytes. */

include/data0type.ic

@@ -161,7 +161,8 @@ UNIV_INLINE
 ulint
 dtype_get_mtype(
 /*============*/
-	const dtype_t*	type)
+				/* out: SQL main data type */
+	const dtype_t*	type)	/* in: data type */
 {
 	ut_ad(type);
 
@@ -174,7 +175,8 @@ UNIV_INLINE
 ulint
 dtype_get_prtype(
 /*=============*/
-	const dtype_t*	type)
+				/* out: precise data type */
+	const dtype_t*	type)	/* in: data type */
 {
 	ut_ad(type);
 
@@ -187,7 +189,9 @@ UNIV_INLINE
 ulint
 dtype_get_len(
 /*==========*/
-	const dtype_t*	type)
+				/* out: fixed length of the type, in bytes,
+				or 0 if variable-length */
+	const dtype_t*	type)	/* in: data type */
 {
 	ut_ad(type);
 

include/dict0dict.h

@@ -164,7 +164,9 @@ UNIV_INLINE
 ulint
 dict_col_get_no(
 /*============*/
-	const dict_col_t*	col);
+					/* out: col->ind, table column
+					position (starting from 0) */
+	const dict_col_t*	col);	/* in: column */
 /*************************************************************************
 Gets the column position in the clustered index. */
 UNIV_INLINE
@@ -915,7 +917,9 @@ UNIV_INLINE
 const dict_col_t*
 dict_field_get_col(
 /*===============*/
-	const dict_field_t*	field);
+					/* out: field->col,
+					pointer to the table column */
+	const dict_field_t*	field);	/* in: index field */
 #ifndef UNIV_HOTBACKUP
 /**************************************************************************
 Returns an index object if it is found in the dictionary cache.

include/dict0dict.ic

@@ -131,7 +131,9 @@ UNIV_INLINE
 ulint
 dict_col_get_no(
 /*============*/
-	const dict_col_t*	col)
+					/* out: col->ind, table column
+					position (starting from 0) */
+	const dict_col_t*	col)	/* in: column */
 {
 	ut_ad(col);
 
@@ -590,7 +592,9 @@ UNIV_INLINE
 const dict_col_t*
 dict_field_get_col(
 /*===============*/
-	const dict_field_t*	field)
+					/* out: field->col,
+					pointer to the table column */
+	const dict_field_t*	field)	/* in: index field */
 {
 	ut_ad(field);
 

include/ha_prototypes.h

@@ -26,19 +26,22 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 InnoDB's C-code. */
 
 /*************************************************************************
-Wrapper around MySQL's copy_and_convert function, see it for
-documentation. */
+Wrapper around MySQL's copy_and_convert function. */
 UNIV_INTERN
 ulint
 innobase_convert_string(
 /*====================*/
-	void*		to,
-	ulint		to_length,
-	CHARSET_INFO*	to_cs,
-	const void*	from,
-	ulint		from_length,
-	CHARSET_INFO*	from_cs,
-	uint*		errors);
+					/* out: number of bytes copied
+					to 'to' */
+	void*		to,		/* out: converted string */
+	ulint		to_length,	/* in: number of bytes reserved
+					for the converted string */
+	CHARSET_INFO*	to_cs,		/* in: character set to convert to */
+	const void*	from,		/* in: string to convert */
+	ulint		from_length,	/* in: number of bytes to convert */
+	CHARSET_INFO*	from_cs,	/* in: character set to convert from */
+	uint*		errors);	/* out: number of errors encountered
+					during the conversion */
 
 /***********************************************************************
 Formats the raw data in "data" (in InnoDB on-disk format) that is of

include/os0proc.h

@@ -49,6 +49,7 @@ UNIV_INTERN
 ulint
 os_proc_get_number(void);
 /*====================*/
+				/* out: process id as a number */
 /********************************************************************
 Allocates large pages memory. */
 UNIV_INTERN

include/os0thread.h

@@ -71,8 +71,8 @@ UNIV_INTERN
 ulint
 os_thread_pf(
 /*=========*/
-				/* out: unsigned long int */
-	os_thread_id_t	a);	/* in: thread or thread id */
+				/* out: thread identifier as a number */
+	os_thread_id_t	a);	/* in: OS thread identifier */
 /********************************************************************
 Creates a new thread of execution. The execution starts from
 the function given. The start function takes a void* parameter
@@ -152,6 +152,7 @@ UNIV_INTERN
 ulint
 os_thread_get_last_error(void);
 /*==========================*/
+				/* out: last error on Windows, 0 otherwise */
 
 #ifndef UNIV_NONINL
 #include "os0thread.ic"

include/row0mysql.h

@@ -249,7 +249,9 @@ UNIV_INTERN
 ibool
 row_table_got_default_clust_index(
 /*==============================*/
-	const dict_table_t*	table);
+					/* out: TRUE if the clustered index
+					was generated automatically */
+	const dict_table_t*	table);	/* in: table */
 /*************************************************************************
 Calculates the key number used inside MySQL for an Innobase index. We have
 to take into account if we generated a default clustered index for the table */
@@ -257,7 +259,9 @@ UNIV_INTERN
 ulint
 row_get_mysql_key_number_for_index(
 /*===============================*/
-	const dict_index_t*	index);
+					/* out: the key number used
+					inside MySQL */
+	const dict_index_t*	index);	/* in: index */
 /*************************************************************************
 Does an update or delete of a row for MySQL. */
 UNIV_INTERN

include/row0sel.h

@@ -67,8 +67,9 @@ UNIV_INLINE
 plan_t*
 sel_node_get_nth_plan(
 /*==================*/
-	sel_node_t*	node,
-	ulint		i);
+				/* out: plan node */
+	sel_node_t*	node,	/* in: select node */
+	ulint		i);	/* in: get ith plan node */
 /**************************************************************************
 Performs a select step. This is a high-level function used in SQL execution
 graphs. */

include/sync0rw.h

@@ -141,7 +141,8 @@ UNIV_INTERN
 ibool
 rw_lock_validate(
 /*=============*/
-	rw_lock_t*	lock);
+				/* out: TRUE */
+	rw_lock_t*	lock);	/* in: rw-lock */
 #endif /* UNIV_DEBUG */
 /******************************************************************
 NOTE! The following macros should be used in rw s-locking, not the
@@ -357,24 +358,33 @@ ulint
 rw_lock_get_x_lock_count(
 /*=====================*/
 					/* out: value of writer_count */
-	rw_lock_t*	lock);	/* in: rw-lock */
+	const rw_lock_t*	lock);	/* in: rw-lock */
 /************************************************************************
-Accessor functions for rw lock. */
+Check if there are threads waiting for the rw-lock. */
 UNIV_INLINE
 ulint
 rw_lock_get_waiters(
 /*================*/
-	rw_lock_t*	lock);
+					/* out: 1 if waiters, 0 otherwise */
+	const rw_lock_t*	lock);	/* in: rw-lock */
+/**********************************************************************
+Returns the write-status of the lock - this function made more sense
+with the old rw_lock implementation. */
 UNIV_INLINE
 ulint
 rw_lock_get_writer(
 /*===============*/
-	rw_lock_t*	lock);
+					/* out: RW_LOCK_NOT_LOCKED,
+					RW_LOCK_EX, RW_LOCK_WAIT_EX */
+	const rw_lock_t*	lock);	/* in: rw-lock */
+/**********************************************************************
+Returns the number of readers. */
 UNIV_INLINE
 ulint
 rw_lock_get_reader_count(
 /*=====================*/
-	rw_lock_t*	lock);
+					/* out: number of readers */
+	const rw_lock_t*	lock);	/* in: rw-lock */
 /**********************************************************************
 Decrements lock_word the specified amount if it is greater than 0.
 This is used by both s_lock and x_lock operations. */
@@ -383,7 +393,7 @@ ibool
 rw_lock_lock_word_decr(
 /*===================*/
 					/* out: TRUE if decr occurs */
-	rw_lock_t*	lock,		/* in: rw-lock */
+	rw_lock_t*	lock,		/* in/out: rw-lock */
 	ulint		amount);	/* in: amount to decrement */
 /**********************************************************************
 Increments lock_word the specified amount and returns new value. */
@@ -391,9 +401,10 @@ UNIV_INLINE
 lint
 rw_lock_lock_word_incr(
 /*===================*/
-					/* out: TRUE if decr occurs */
-	rw_lock_t*	lock,
-	ulint		amount);	/* in: rw-lock */
+					/* out: lock->lock_word after
+					increment */
+	rw_lock_t*	lock,		/* in/out: rw-lock */
+	ulint		amount);	/* in: amount to increment */
 /**********************************************************************
 This function sets the lock->writer_thread and lock->recursive fields.
 For platforms where we are using atomic builtins instead of lock->mutex

include/sync0rw.ic

@@ -67,13 +67,13 @@ rw_lock_remove_debug_info(
 #endif /* UNIV_SYNC_DEBUG */
 
 /************************************************************************
-Accessor functions for rw lock. */
+Check if there are threads waiting for the rw-lock. */
 UNIV_INLINE
 ulint
 rw_lock_get_waiters(
 /*================*/
 					/* out: 1 if waiters, 0 otherwise */
-	rw_lock_t*	lock)	/* in: rw-lock */
+	const rw_lock_t*	lock)	/* in: rw-lock */
 {
 	return(lock->waiters);
 }
@@ -86,7 +86,7 @@ UNIV_INLINE
 void
 rw_lock_set_waiter_flag(
 /*====================*/
-	rw_lock_t*	lock)	/* in: rw-lock */
+	rw_lock_t*	lock)	/* in/out: rw-lock */
 {
 #ifdef INNODB_RW_LOCKS_USE_ATOMICS
 	os_compare_and_swap_ulint(&lock->waiters, 0, 1);
@@ -103,7 +103,7 @@ UNIV_INLINE
 void
 rw_lock_reset_waiter_flag(
 /*======================*/
-	rw_lock_t*	lock)	/* in: rw-lock */
+	rw_lock_t*	lock)	/* in/out: rw-lock */
 {
 #ifdef INNODB_RW_LOCKS_USE_ATOMICS
 	os_compare_and_swap_ulint(&lock->waiters, 1, 0);
@@ -119,10 +119,12 @@ UNIV_INLINE
 ulint
 rw_lock_get_writer(
 /*===============*/
-	rw_lock_t*	lock)
+					/* out: RW_LOCK_NOT_LOCKED,
+					RW_LOCK_EX, RW_LOCK_WAIT_EX */
+	const rw_lock_t*	lock)	/* in: rw-lock */
 {
 	lint lock_word = lock->lock_word;
-	if(lock_word > 0) {
+	if (lock_word > 0) {
 		/* return NOT_LOCKED in s-lock state, like the writer
 		member of the old lock implementation. */
 		return(RW_LOCK_NOT_LOCKED);
@@ -135,15 +137,16 @@ rw_lock_get_writer(
 }
 
 /**********************************************************************
-Returns number of readers. */
+Returns the number of readers. */
 UNIV_INLINE
 ulint
 rw_lock_get_reader_count(
 /*=====================*/
-	rw_lock_t*	lock)
+					/* out: number of readers */
+	const rw_lock_t*	lock)	/* in: rw-lock */
 {
 	lint lock_word = lock->lock_word;
-	if(lock_word > 0) {
+	if (lock_word > 0) {
 		/* s-locked, no x-waiters */
 		return(X_LOCK_DECR - lock_word);
 	} else if (lock_word < 0 && lock_word > -X_LOCK_DECR) {
@@ -172,11 +175,11 @@ ulint
 rw_lock_get_x_lock_count(
 /*=====================*/
 					/* out: value of writer_count */
-	rw_lock_t*	lock)	/* in: rw-lock */
+	const rw_lock_t*	lock)	/* in: rw-lock */
 {
 	lint lock_copy = lock->lock_word;
 	/* If there is a reader, lock_word is not divisible by X_LOCK_DECR */
-	if(lock_copy > 0 || (-lock_copy) % X_LOCK_DECR != 0) {
+	if (lock_copy > 0 || (-lock_copy) % X_LOCK_DECR != 0) {
 		return(0);
 	}
 	return(((-lock_copy) / X_LOCK_DECR) + 1);
@@ -193,15 +196,13 @@ ibool
 rw_lock_lock_word_decr(
 /*===================*/
 					/* out: TRUE if decr occurs */
-	rw_lock_t*	lock,	/* in: rw-lock */
-	ulint		amount)	/* in: amount of decrement */
+	rw_lock_t*	lock,		/* in/out: rw-lock */
+	ulint		amount);	/* in: amount to decrement */
 {
-
 #ifdef INNODB_RW_LOCKS_USE_ATOMICS
-
         lint local_lock_word = lock->lock_word;
 	while (local_lock_word > 0) {
-		if(os_compare_and_swap_lint(&lock->lock_word,
+		if (os_compare_and_swap_lint(&lock->lock_word,
 					     local_lock_word,
 					     local_lock_word - amount)) {
 			return(TRUE);
@@ -209,39 +210,32 @@ rw_lock_lock_word_decr(
 		local_lock_word = lock->lock_word;
 	}
 	return(FALSE);
-
 #else /* INNODB_RW_LOCKS_USE_ATOMICS */
-
 	ibool success = FALSE;
 	mutex_enter(&(lock->mutex));
-	if(lock->lock_word > 0) {
+	if (lock->lock_word > 0) {
 		lock->lock_word -= amount;
 		success = TRUE;
 	}
 	mutex_exit(&(lock->mutex));
 	return(success);
-
 #endif /* INNODB_RW_LOCKS_USE_ATOMICS */
 }
 
 /**********************************************************************
-Two different implementations for incrementing the lock_word of a rw_lock:
-one for systems supporting atomic operations, one for others.
-Returns the value of lock_word after increment. */
+Increments lock_word the specified amount and returns new value. */
 UNIV_INLINE
 lint
 rw_lock_lock_word_incr(
 /*===================*/
-				/* out: lock->lock_word after increment */
-	rw_lock_t*	lock,	/* in: rw-lock */
+					/* out: lock->lock_word after
+					increment */
+	rw_lock_t*	lock,		/* in/out: rw-lock */
 	ulint		amount)		/* in: amount of increment */
 {
 #ifdef INNODB_RW_LOCKS_USE_ATOMICS
-
 	return(os_atomic_increment_lint(&lock->lock_word, amount));
-
 #else /* INNODB_RW_LOCKS_USE_ATOMICS */
-
 	lint local_lock_word;
 
 	mutex_enter(&(lock->mutex));
@@ -252,7 +246,6 @@ rw_lock_lock_word_incr(
 	mutex_exit(&(lock->mutex));
 
         return(local_lock_word);
-
 #endif /* INNODB_RW_LOCKS_USE_ATOMICS */
 }
 

include/sync0sync.h

@@ -160,6 +160,7 @@ void
 mutex_exit(
 /*=======*/
 	mutex_t*	mutex);	/* in: pointer to mutex */
+#ifdef UNIV_SYNC_DEBUG
 /**********************************************************************
 Returns TRUE if no mutex or rw-lock is currently locked.
 Works only in the debug version. */
@@ -167,6 +168,8 @@ UNIV_INTERN
 ibool
 sync_all_freed(void);
 /*================*/
+			/* out: TRUE if no mutexes and rw-locks reserved */
+#endif /* UNIV_SYNC_DEBUG */
 /*#####################################################################
 FUNCTION PROTOTYPES FOR DEBUGGING */
 /***********************************************************************
@@ -190,7 +193,8 @@ UNIV_INTERN
 ibool
 mutex_validate(
 /*===========*/
-	const mutex_t*	mutex);
+				/* out: TRUE */
+	const mutex_t*	mutex);	/* in: mutex */
 /**********************************************************************
 Checks that the current thread owns the mutex. Works only
 in the debug version. */
@@ -260,6 +264,7 @@ UNIV_INTERN
 ulint
 mutex_n_reserved(void);
 /*==================*/
+				/* out: number of reserved mutexes */
 #endif /* UNIV_SYNC_DEBUG */
 /**********************************************************************
 NOT to be used outside this module except in debugging! Gets the value

include/ut0ut.h

@@ -165,6 +165,7 @@ UNIV_INTERN
 ib_time_t
 ut_time(void);
 /*=========*/
+				/* out: system time */
 /**************************************************************
 Returns system time.
 Upon successful completion, the value 0 is returned; otherwise the

lock/lock0lock.c

@@ -4343,6 +4343,7 @@ static
 ulint
 lock_get_n_rec_locks(void)
 /*======================*/
+				/* out: number of record locks */
 {
 	lock_t*	lock;
 	ulint	n_locks	= 0;

log/log0log.c

@@ -177,6 +177,7 @@ static
 ib_uint64_t
 log_buf_pool_get_oldest_modification(void)
 /*======================================*/
+				/* out: LSN of oldest modification */
 {
 	ib_uint64_t	lsn;
 

os/os0proc.c

@@ -52,6 +52,7 @@ UNIV_INTERN
 ulint
 os_proc_get_number(void)
 /*====================*/
+				/* out: process id as a number */
 {
 #ifdef __WIN__
 	return((ulint)GetCurrentProcessId());

os/os0thread.c

@@ -67,7 +67,8 @@ UNIV_INTERN
 ulint
 os_thread_pf(
 /*=========*/
-	os_thread_id_t	a)
+				/* out: thread identifier as a number */
+	os_thread_id_t	a)	/* in: OS thread identifier */
 {
 #ifdef UNIV_HPUX10
 	/* In HP-UX-10.20 a pthread_t is a struct of 3 fields: field1, field2,
@@ -361,6 +362,7 @@ UNIV_INTERN
 ulint
 os_thread_get_last_error(void)
 /*==========================*/
+				/* out: last error on Windows, 0 otherwise */
 {
 #ifdef __WIN__
 	return(GetLastError());

page/page0zip.c

@@ -651,9 +651,9 @@ static
 void*
 page_zip_malloc(
 /*============*/
-	void*	opaque,
-	uInt	items,
-	uInt	size)
+	void*	opaque,	/* in/out: memory heap */
+	uInt	items,	/* in: number of items to allocate */
+	uInt	size)	/* in: size of an item in bytes */
 {
 	return(mem_heap_alloc(opaque, items * size));
 }
@@ -664,8 +664,8 @@ static
 void
 page_zip_free(
 /*==========*/
-	void*	opaque __attribute__((unused)),
-	void*	address __attribute__((unused)))
+	void*	opaque __attribute__((unused)),	/* in: memory heap */
+	void*	address __attribute__((unused)))/* in: object to free */
 {
 }
 

row/row0mysql.c

@@ -1616,7 +1616,9 @@ UNIV_INTERN
 ibool
 row_table_got_default_clust_index(
 /*==============================*/
-	const dict_table_t*	table)
+					/* out: TRUE if the clustered index
+					was generated automatically */
+	const dict_table_t*	table)	/* in: table */
 {
 	const dict_index_t*	clust_index;
 
@@ -1632,7 +1634,9 @@ UNIV_INTERN
 ulint
 row_get_mysql_key_number_for_index(
 /*===============================*/
-	const dict_index_t*	index)
+					/* out: the key number used
+					inside MySQL */
+	const dict_index_t*	index)	/* in: index */
 {
 	const dict_index_t*	ind;
 	ulint			i;

srv/srv0start.c

@@ -444,7 +444,9 @@ static
 os_thread_ret_t
 io_handler_thread(
 /*==============*/
-	void*	arg)
+			/* out: OS_THREAD_DUMMY_RETURN */
+	void*	arg)	/* in: pointer to the number of the segment in
+			the aio array */
 {
 	ulint	segment;
 	ulint	i;

sync/sync0rw.c

@@ -194,6 +194,7 @@ static
 rw_lock_debug_t*
 rw_lock_debug_create(void)
 /*======================*/
+				/* out, own: debug info struct */
 {
 	return((rw_lock_debug_t*) mem_alloc(sizeof(rw_lock_debug_t)));
 }
@@ -329,7 +330,8 @@ UNIV_INTERN
 ibool
 rw_lock_validate(
 /*=============*/
-	rw_lock_t*	lock)
+				/* out: TRUE */
+	rw_lock_t*	lock)	/* in: rw-lock */
 {
 	ut_a(lock);
 

sync/sync0sync.c

@@ -374,7 +374,8 @@ UNIV_INTERN
 ibool
 mutex_validate(
 /*===========*/
-	const mutex_t*	mutex)
+				/* out: TRUE */
+	const mutex_t*	mutex)	/* in: mutex */
 {
 	ut_a(mutex);
 	ut_a(mutex->magic_n == MUTEX_MAGIC_N);
@@ -703,6 +704,7 @@ UNIV_INTERN
 ulint
 mutex_n_reserved(void)
 /*==================*/
+				/* out: number of reserved mutexes */
 {
 	mutex_t*	mutex;
 	ulint		count		= 0;
@@ -735,6 +737,7 @@ UNIV_INTERN
 ibool
 sync_all_freed(void)
 /*================*/
+			/* out: TRUE if no mutexes and rw-locks reserved */
 {
 	return(mutex_n_reserved() + rw_lock_n_locked() == 0);
 }

trx/trx0roll.c

@@ -614,6 +614,7 @@ UNIV_INTERN
 trx_undo_arr_t*
 trx_undo_arr_create(void)
 /*=====================*/
+				/* out, own: undo number array */
 {
 	trx_undo_arr_t*	arr;
 	mem_heap_t*	heap;

ut/ut0ut.c

@@ -116,6 +116,7 @@ UNIV_INTERN
 ib_time_t
 ut_time(void)
 /*=========*/
+				/* out: system time */
 {
 	return(time(NULL));
 }