branches/zip: Adjust some function comments after r5091.

dict/dict0load.c

@@ -41,15 +41,15 @@ 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 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(

handler/ha_innodb.cc

@@ -294,25 +294,27 @@ 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 */
+        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 */
+				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,
+	handlerton*	hton,	/*!< in: InnoDB handlerton */
 	XID*		xid_list,/*!< in/out: prepared transactions */
 	uint		len);	/*!< in: number of slots in xid_list */
 /***********************************************************************
@@ -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 */
+        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 */
+				FALSE - the current SQL statement
+				ended */
 {
 	int error = 0;
 	trx_t* trx = check_trx_exists(thd);
@@ -8976,13 +8980,13 @@ 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,
+	handlerton*	hton,	/*!< in: InnoDB handlerton */
 	XID*		xid_list,/*!< in/out: prepared transactions */
 	uint		len)	/*!< in: number of slots in xid_list */
 {

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"

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/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 {\

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);
 }