branches/zip: Adjust some function comments after r5091.

dict/dict0load.c

@@ -41,16 +41,16 @@ Created 4/24/1996 Heikki Tuuri
 #include "srv0srv.h"
 
 /********************************************************************
-Returns TRUE if index's i'th column's name is 'name' .
-@return	 */
+Compare the name of an index column.
+@return	TRUE if the i'th column of index is 'name'. */
 static
 ibool
 name_of_col_is(
 /*===========*/
-	dict_table_t*	table,	/*!< in: table */
-	dict_index_t*	index,	/*!< in: index */
-	ulint		i,	/*!< in:  */
-	const char*	name)	/*!< in: name to compare to */
+	const dict_table_t*	table,	/*!< in: table */
+	const dict_index_t*	index,	/*!< in: index */
+	ulint			i,	/*!< in: index field offset */
+	const char*		name)	/*!< in: name to compare to */
 {
 	ulint	tmp = dict_col_get_no(dict_field_get_col(
 					      dict_index_get_nth_field(

handler/ha_innodb.cc

@@ -294,27 +294,29 @@ static handler *innobase_create_handler(handlerton *hton,
 }
 
 /***********************************************************************
-This function is used to prepare X/Open XA distributed transaction
+This function is used to prepare an X/Open XA distributed transaction.
 @return	0 or error number */
 static
 int
 innobase_xa_prepare(
 /*================*/
-	handlerton* hton,
-	THD*	thd,	/*!< in: handle to the MySQL thread of the user
-			whose XA transaction should be prepared */
-	bool	all);	/*!< in: TRUE - commit transaction
-			FALSE - the current SQL statement ended */
+        handlerton*	hton,	/*!< in: InnoDB handlerton */
+	THD*		thd,	/*!< in: handle to the MySQL thread of
+				the user whose XA transaction should
+				be prepared */
+	bool		all);	/*!< in: TRUE - commit transaction
+				FALSE - the current SQL statement
+				ended */
 /***********************************************************************
-This function is used to recover X/Open XA distributed transactions
+This function is used to recover X/Open XA distributed transactions.
 @return	number of prepared transactions stored in xid_list */
 static
 int
 innobase_xa_recover(
 /*================*/
-	handlerton* hton,
-	XID*	xid_list,	/*!< in/out: prepared transactions */
-	uint	len);		/*!< in: number of slots in xid_list */
+	handlerton*	hton,	/*!< in: InnoDB handlerton */
+	XID*		xid_list,/*!< in/out: prepared transactions */
+	uint		len);	/*!< in: number of slots in xid_list */
 /***********************************************************************
 This function is used to commit one X/Open XA distributed transaction
 which is in the prepared state
@@ -4128,7 +4130,7 @@ ha_innobase::innobase_reset_autoinc(
 /************************************************************************
 Store the autoinc value in the table. The autoinc value is only set if
 it's greater than the existing autoinc value in the table.
-@return	DB_SUCCES if all went well else error code */
+@return	DB_SUCCESS if all went well else error code */
 UNIV_INTERN
 ulint
 ha_innobase::innobase_set_max_autoinc(
@@ -8876,17 +8878,19 @@ innobase_get_at_most_n_mbchars(
 }
 
 /***********************************************************************
-This function is used to prepare X/Open XA distributed transaction
+This function is used to prepare an X/Open XA distributed transaction.
 @return	0 or error number */
 static
 int
 innobase_xa_prepare(
 /*================*/
-        handlerton *hton,
-	THD*	thd,	/*!< in: handle to the MySQL thread of the user
-			whose XA transaction should be prepared */
-	bool	all)	/*!< in: TRUE - commit transaction
-			FALSE - the current SQL statement ended */
+        handlerton*	hton,	/*!< in: InnoDB handlerton */
+	THD*		thd,	/*!< in: handle to the MySQL thread of
+				the user whose XA transaction should
+				be prepared */
+	bool		all)	/*!< in: TRUE - commit transaction
+				FALSE - the current SQL statement
+				ended */
 {
 	int error = 0;
 	trx_t* trx = check_trx_exists(thd);
@@ -8976,15 +8980,15 @@ innobase_xa_prepare(
 }
 
 /***********************************************************************
-This function is used to recover X/Open XA distributed transactions
+This function is used to recover X/Open XA distributed transactions.
 @return	number of prepared transactions stored in xid_list */
 static
 int
 innobase_xa_recover(
 /*================*/
-        handlerton *hton,
-	XID*	xid_list,	/*!< in/out: prepared transactions */
-	uint	len)		/*!< in: number of slots in xid_list */
+	handlerton*	hton,	/*!< in: InnoDB handlerton */
+	XID*		xid_list,/*!< in/out: prepared transactions */
+	uint		len)	/*!< in: number of slots in xid_list */
 {
 	DBUG_ASSERT(hton == innodb_hton_ptr);
 

handler/win_delay_loader.cc

@@ -73,7 +73,7 @@ ulong*			wdl_specialflag;
 int*			wdl_my_umask;
 
 /***********************************************************************
-The preffered load-address defined in PE (portable executable format). */
+The preferred load-address defined in PE (portable executable format). */
 #if defined(_M_IA64)
 #pragma section(".base", long, read)
 extern "C"

ibuf/ibuf0ibuf.c

@@ -1142,7 +1142,7 @@ ibuf_dummy_index_add_col(
 }
 /************************************************************************
 Deallocates a dummy index for inserting a record to a non-clustered index.
- */
+*/
 static
 void
 ibuf_dummy_index_free(

include/buf0buf.h

@@ -1447,7 +1447,7 @@ FILE_PAGE => NOT_USED	NOTE: This transition is allowed if and only if
 				(1) buf_fix_count == 0,
 				(2) oldest_modification == 0, and
 				(3) io_fix == 0.
- */
+*/
 
 #ifndef UNIV_NONINL
 #include "buf0buf.ic"

include/ha0storage.h

@@ -105,13 +105,12 @@ ha_storage_empty(
 /***********************************************************************
 Frees a hash storage and everything it contains, it cannot be used after
 this call.
-This invalidates any pointers previously returned by ha_storage_put().
- */
+This invalidates any pointers previously returned by ha_storage_put(). */
 UNIV_INLINE
 void
 ha_storage_free(
 /*============*/
-	ha_storage_t*	storage);	/*!< in/out: hash storage */
+	ha_storage_t*	storage);	/*!< in, own: hash storage */
 
 /***********************************************************************
 Gets the size of the memory used by a storage.

include/ha0storage.ic

@@ -111,13 +111,12 @@ ha_storage_empty(
 /***********************************************************************
 Frees a hash storage and everything it contains, it cannot be used after
 this call.
-This invalidates any pointers previously returned by ha_storage_put().
- */
+This invalidates any pointers previously returned by ha_storage_put(). */
 UNIV_INLINE
 void
 ha_storage_free(
 /*============*/
-	ha_storage_t*	storage)	/*!< in/out: hash storage */
+	ha_storage_t*	storage)	/*!< in, own: hash storage */
 {
 	/* order is important because the pointer storage->hash is
 	within the heap */

include/mem0dbg.ic

@@ -62,7 +62,7 @@ void
 mem_erase_buf(
 /*==========*/
 	byte*	buf,	/*!< in: pointer to buffer */
-	ulint	 n);	 /*!< in: length of buffer */
+	ulint	n);	/*!< in: length of buffer */
 /*******************************************************************
 Inserts a created memory heap to the hash table of
 current allocated memory heaps.

include/pars0pars.h

@@ -470,7 +470,7 @@ UNIV_INTERN
 void
 pars_info_free(
 /*===========*/
-	pars_info_t*	info);	/*!< in: info struct */
+	pars_info_t*	info);	/*!< in, own: info struct */
 
 /********************************************************************
 Add bound literal. */

include/trx0trx.h

@@ -398,8 +398,8 @@ trx_is_interrupted(
 /***********************************************************************
 Calculates the "weight" of a transaction. The weight of one transaction
 is estimated as the number of altered rows + the number of locked rows.
- */
-
+@param t	transaction
+@return		transaction weight */
 #define TRX_WEIGHT(t)	\
 	ut_dulint_add((t)->undo_no, UT_LIST_GET_LEN((t)->trx_locks))
 

include/ut0lst.h

@@ -58,8 +58,7 @@ struct LRU_node_struct {
 	...
 }
 The example implements an LRU list of name LRU_list. Its nodes are of type
-LRU_node_t.
- */
+LRU_node_t. */
 
 #define UT_LIST_NODE_T(TYPE)\
 struct {\

mem/mem0dbg.c

@@ -280,7 +280,7 @@ void
 mem_erase_buf(
 /*==========*/
 	byte*	buf,	/*!< in: pointer to buffer */
-	ulint	 n)	 /*!< in: length of buffer */
+	ulint	n)	/*!< in: length of buffer */
 {
 	byte*	ptr;
 

pars/lexyy.c

@@ -747,13 +747,13 @@ Linux.
 static ulint	stringbuf_len_alloc = 0; /* Allocated length */
 static ulint	stringbuf_len = 0; /* Current length */
 static char*	stringbuf; /* Start of buffer */
-/* Appends a string to the buffer. */
+/** Appends a string to the buffer. */
 static
 void
 string_append(
 /*==========*/
-	const char*	str,	/* in: string to be appended */
-	ulint		len)	/* in: length of the string */
+	const char*	str,	/*!< in: string to be appended */
+	ulint		len)	/*!< in: length of the string */
 {
 	if (stringbuf == NULL) {
 		stringbuf = malloc(1);

pars/pars0lex.l

@@ -70,13 +70,13 @@ Created 12/14/1997 Heikki Tuuri
 static ulint	stringbuf_len_alloc = 0; /* Allocated length */
 static ulint	stringbuf_len = 0; /* Current length */
 static char*	stringbuf; /* Start of buffer */
-/* Appends a string to the buffer. */
+/** Appends a string to the buffer. */
 static
 void
 string_append(
 /*==========*/
-	const char*	str,	/* in: string to be appended */
-	ulint		len)	/* in: length of the string */
+	const char*	str,	/*!< in: string to be appended */
+	ulint		len)	/*!< in: length of the string */
 {
 	if (stringbuf == NULL) {
 		stringbuf = malloc(1);

pars/pars0pars.c

@@ -1952,7 +1952,7 @@ UNIV_INTERN
 void
 pars_info_free(
 /*===========*/
-	pars_info_t*	info)	/*!< in: info struct */
+	pars_info_t*	info)	/*!< in, own: info struct */
 {
 	mem_heap_free(info->heap);
 }