pmplib-commits

[<ny...@us...>]

Revision: 321
          http://svn.sourceforge.net/pmplib/?rev=321&view=rev
Author:   nyaochi
Date:     2007-02-09 20:29:14 -0800 (Fri, 09 Feb 2007)

Log Message:
-----------
The completion of initial draft of PMPlib API documentation.

Modified Paths:
--------------
    trunk/pmplib/include/pmplib/filepath.h
    trunk/pmplib/include/pmplib/pmp.h
    trunk/pmplib/include/pmplib/ucs2char.h

Modified: trunk/pmplib/include/pmplib/filepath.h
===================================================================
--- trunk/pmplib/include/pmplib/filepath.h	2007-02-09 16:13:11 UTC (rev 320)
+++ trunk/pmplib/include/pmplib/filepath.h	2007-02-10 04:29:14 UTC (rev 321)
@@ -42,14 +42,18 @@
  * \addtogroup filepath File/Path Manupulation API
  * @{
  *
- *	The PMPlib File/Path Manupulation API is a utility for file-systems and
- *	pathnames.
+ *	The PMPlib File/Path Manupulation API is a utility for operations on file
+ *	systems and string manupulation for file/path names. This API encapsulates
+ *	the difference between Win32 and POSIX APIs, UCS-2 string and multi-byte
+ *	characters, and path characters ('\\' or '/').
  */
 
 /** 
- * \addtogroup filepath_string file/path string API
+ * \addtogroup filepath_string String manupulation for file and path names
  * @{
  *
+ *	String manupulation routines manage strings so that they are grammartical
+ *	for path and file names.
  */
 
 /**
@@ -215,9 +219,12 @@
 /** @} */
 
 /** 
- * \addtogroup filepath_filedir file/directory manupulation API
+ * \addtogroup filepath_filedir File and directory manupulation
  * @{
  *
+ *	File and directory manupulation routines provide a unified API to
+ *	manupulate a file system, encapsulating the difference between Win32 and
+ *	POSIX APIs.
  */
 
 /**

Modified: trunk/pmplib/include/pmplib/pmp.h
===================================================================
--- trunk/pmplib/include/pmplib/pmp.h	2007-02-09 16:13:11 UTC (rev 320)
+++ trunk/pmplib/include/pmplib/pmp.h	2007-02-10 04:29:14 UTC (rev 321)
@@ -48,14 +48,22 @@
 /** 
  * \addtogroup pmp PMPlib APIs
  * @{ 
+ *
+ *	The PMPlib APIs define the programing interface for both applications
+ *	and driver modules.
  */
 
 /*
  * Forward structure declarations.
  */
-struct tag_pmp_t;			typedef struct tag_pmp_t pmp_t;
-struct tag_pmp_music_t;		typedef struct tag_pmp_music_t pmp_music_t;
+struct tag_pmp_t;
+/** Synonym of struct tag_pmp_t. */
+typedef struct tag_pmp_t pmp_t;
 
+struct tag_pmp_music_t;
+/** Synonym of struct tag_pmp_music_t. */
+typedef struct tag_pmp_music_t pmp_music_t;
+
 /**
  * Status codes.
  */
@@ -146,8 +154,10 @@
 
 
 /**
- * @defgroup device PMPlib Device API
+ * @defgroup device PMPlib device API
  * @{ 
+ *
+ *	PMPlib Device API is the root interface to a driver.
  */
 
 /** Maximum size, in chars, of a device description. */
@@ -296,8 +306,11 @@
  */
 
 /**
- * @defgroup music PMPlib Music API
+ * @defgroup music PMPlib music API
  * @{ 
+ *
+ *	PMPlib Music API provides the interface to manage music files in a portable
+ *	media device.
  */
 
 /**
@@ -418,6 +431,10 @@
 	 */
 	uint32_t		ts_import;
 };
+
+/**
+ * Synonym of struct tag_pmp_music_record_t.
+ */
 typedef struct tag_pmp_music_record_t pmp_music_record_t;
 
 /**
@@ -622,7 +639,7 @@
  *	This function frees the memory blocks used by each record in the array and
  *	the array.
  *
- *	@param	record			The pointer to pmp_music_record_t array.
+ *	@param	records			The pointer to pmp_music_record_t array.
  *	@param	num_records		The number of elements in the array.
  */
 PMPAPI void pmplib_records_finish(pmp_music_record_t* records, int num_records);
@@ -683,7 +700,7 @@
  *
  *	@param	dst				The destination array.
  *	@param	src				The source array.
- *	@param	num_records		The number of elements in the source array.
+ *	@param	num_playlists	The number of elements in the source array.
  */
 PMPAPI void pmplib_playlists_clone(pmp_playlist_t* dst, const pmp_playlist_t* src, int num_playlists);
 
@@ -692,8 +709,10 @@
  */
 
 /** 
- * \addtogroup pmp_export Export functions of a driver module
+ * \addtogroup pmp_export PMPlib export functions for a driver module
  * @{
+ *
+ *	This API defines the interface that a driver module must implement.
  */
 
 /**
@@ -755,8 +774,10 @@
  */
 
 /** 
- * \addtogroup pmp_driver Driver utility API
+ * \addtogroup pmp_driver PMPlib miscellaneous routines
  * @{
+ *
+ *	PMPlib miscellaneous routines provide the utility for a driver module.
  */
 
 /**
@@ -794,7 +815,7 @@
 
 
 /**
- * @defgroup pmplib PMPlib Helper API
+ * @defgroup pmplib PMPlib helper API
  * @{ 
  *
  *	The PMPlib Helper API provides the utility for choosing a suitable PMPlib
@@ -922,14 +943,14 @@
  *	to the driver will be returned in the \a pmp argument.
  *
  *	@param	pmplib			The pointer to the ::pmplib_t instance.
+ *	@param	ptr_pmp			The pointer to the buffer to receive the pointer
+ *							to the driver interface (::pmp_t instance).
  *	@param	path_to_device	A UCS-2 string representing the location of the
  *							target device. This parameter cannot be \c NULL.
  *	@param	id				A C-string representing the device identifier of
  *							the target device. If this argument is \c NULL,
  *							this function tries to recognize the model of the
  *							device based on the location (\a path_to_device).
- *	@retval	ptr_pmp			The pointer to the buffer to receive the pointer
- *							to the driver interface (::pmp_t instance).
  *	@retval	result_t		The status code.
  *
  *	@assert

Modified: trunk/pmplib/include/pmplib/ucs2char.h
===================================================================
--- trunk/pmplib/include/pmplib/ucs2char.h	2007-02-09 16:13:11 UTC (rev 320)
+++ trunk/pmplib/include/pmplib/ucs2char.h	2007-02-10 04:29:14 UTC (rev 321)
@@ -40,14 +40,23 @@
  * \addtogroup ucs2 UCS-2 Character/String API
  * @{
  *
- *	The PMPlib UCS-2 character/string API provides a manupulation utility
- *	for characters/strings in UCS-2 encoding. As a number of portable media
- *	players support Unicode for displaying song information, PMPlib deals
- *	with Unicode characters/strings encoded in UCS-2.
+ *	The PMPlib UCS-2 Character/String API provides a manupulation utility
+ *	for characters and strings encoded in UCS-2. The PMPlib supports unicode
+ *	characters and strings in UCS-2 encoding since a number of media players
+ *	employ the encoding for displaying song information. An application is
+ *	required to deal with UCS-2 characters/strings for using the PMPlib API.
+ *	The PMPlib UCS-2 Character/String API implements character encoding
+ *	converter, UCS-2 character routine, ANSI C compatible string manupulator,
+ *	miscellaneous string manupulator, stdio/stdlib compatible routine, and
+ *	memory manager.
  *
- *	The byte order of UCS-2 character is dependent on the CPU architecture
- *	on which this code runs: e.g., little-endian on Intel IA-32/IA-64 and
+ *	A UCS-2 character is represented by a unsigned 16-bit value
+ *	(::ucs2char_t).
+ *	The byte order of a UCS-2 character is dependent on the CPU architecture
+ *	on which this code runs, e.g., little-endian on Intel IA-32/IA-64 and
  *	big-endian on IBM PowerPC.
+ *
+ *	An application must call ucs2init() before using this API.
  */
 
 /**
@@ -56,12 +65,22 @@
 typedef uint16_t ucs2char_t;
 
 /**
- * Initialize the UCS-2 library.
+ * Initialize the UCS-2 Character/String library.
  *
- *	This function initializes internal variables used in the UCS-2 library.
- *	Call this function before using any other functions in this API.
+ *	This function initializes internal variables used in the UCS-2
+ *	Character/String library. Call this function before using any other
+ *	functions in this API.
  *
- *	@retval	int			Zero if succeeded, otherwise non-zero value.
+ *	By default, this function detects the character encoding of multi-byte
+ *	characters on the current system based on the value of LANG variable
+ *	(for POSIX) or via GetACP() function (for Win32). If this function
+ *	could not detect the character encoding of the current system, this
+ *	function would assume it as "UTF-8".
+ *
+ *	@retval	int			Zero if succeeded, otherwise non-zero value. Non-zero
+ *						value indicates that the library could not initialize
+ *						character conversion routines with the character
+ *						encoding of the current locale.
  */
 UCS2API int ucs2init();
 
@@ -70,21 +89,20 @@
  * @defgroup ucs2_conv Character encoding converter
  * @{
  *
- *	This API subset converts the character encoding of a string from one to
- *	another. It supports mutual conversions between:
+ *	Character encoding converter is to convert a string in one character
+ *	encoding to another. The API subset supports mutual conversions between:
  *		UCS-2 and multi-byte character (i.e., \c char);
  *		UCS-2 and UTF-8.
- *
- *	By default, this library detects the character encoding of multi-byte
- *	characters on the current system based on the value of LANG variable
- *	(for POSIX) or via GetACP() function (for Win32).
+ *	Character encoding conversion is performed by MultiByteToWideChar() and
+ *	WideCharToMultiByte() function in Win32 API (for Windows environments)
+ *	iconv() function in libc or libiconv (for POSIX environments).
  */
 
 /**
  * Set the encoding for multi-byte characters (for iconv/libiconv).
  *
- *	This function change the default encoding for multi-byte characters to the
- *	character encoding specified by the \a encoding argument. 
+ *	This function changes the default encoding for multi-byte characters to the
+ *	character encoding specified by the \p encoding argument. 
  *
  *	@param	encoding	The pointer to the string specifying the character
  *						encoding.
@@ -110,8 +128,8 @@
 /**
  * Set the code page for multi-byte characters (for Win32).
  *
- *	This function change the default encoding for multi-byte characters to the
- *	code page specified by the \a cp argument. 
+ *	This function changes the default encoding for multi-byte characters to the
+ *	code page specified by the \p cp argument. 
  *
  *	@param	cp			The code page.
  *
@@ -125,8 +143,6 @@
  *
  *	This function returns the default code page for multi-byte characters. 
  *
- *	@param	cp			The code page.
- *
  *	@note
  *		This function is effective only on Win32 environments.
  */
@@ -135,17 +151,17 @@
 /**
  * Convert a UCS-2 string to multi-byte characters.
  *
- *	@param	mbstr		The pointer to the buffer for receiving multi-byte
+ *	@param	mbstr		The pointer to the buffer that receives multi-byte
  *						characters converted from the UCS-2 string. If
- *						\a mbs_size is zero, this argument is not be used.
+ *						\p mbs_size is zero, this argument is not be used.
  *	@param	mbs_size	The size, in bytes, of the buffer pointed to by the
- *						\a mbstr argument. If this value is zero, the function
+ *						\p mbstr argument. If this value is zero, the function
  *						returns the number of bytes required for the buffer.
  *	@param	ucs2str		The pointer to the UCS-2 string to be converted.
  *	@param	ucs_size	The size, in number of UCS-2 characters, of the UCS-2
- *						string, \a ucs2str.
- *	@retval	size_t		The number of bytes written to \a mbstr buffer if
- *						the conversion is successful. If \a mbs_size is zero,
+ *						string, \p ucs2str.
+ *	@retval	size_t		The number of bytes written to \p mbstr buffer if
+ *						the conversion is successful. If \p mbs_size is zero,
  *						the return value is the required size, in bytes, for a
  *						buffer to receive the converted string. This function
  *						returns zero if an error occurred.
@@ -155,19 +171,19 @@
 /**
  * Convert multi-byte characters to a UCS-2 string.
  *
- *	@param	ucs2str		The pointer to the buffer for receiving UCS-2 string
+ *	@param	ucs2str		The pointer to the buffer that receives UCS-2 string
  *						converted from the multi-byte characters. If
- *						\a ucs_size is zero, this argument is not be used.
+ *						\p ucs_size is zero, this argument is not be used.
  *	@param	ucs_size	The size, in number of UCS-2 characters, of the buffer
- *						pointed to by the \a ucs2str argument. If this value is
+ *						pointed to by the \p ucs2str argument. If this value is
  *						zero, the function returns the number of UCS-2
  *						characters required for the buffer.
  *	@param	mbstr		The pointer to the multi-byte characters to be
  *						converted.
  *	@param	mbs_size	The size, in bytes, of the multi-byte characters,
- *						\a mbstr.
- *	@retval	size_t		The number of UCS-2 characters written to \a ucs2str
- *						buffer if the conversion is successful. If \a ucs_size
+ *						\p mbstr.
+ *	@retval	size_t		The number of UCS-2 characters written to \p ucs2str
+ *						buffer if the conversion is successful. If \p ucs_size
  *						is zero, the return value is the required size, in
  *						number of UCS-2 characters, for a buffer to receive the
  *						converted string. This function returns zero if an error
@@ -178,44 +194,44 @@
 /**
  * Convert multi-byte characters in a specific encoding to a UCS-2 string.
  *
- *	@param	ucs2str		The pointer to the buffer for receiving UCS-2 string
+ *	@param	ucs2str		The pointer to the buffer that receives UCS-2 string
  *						converted from the multi-byte characters. If
- *						\a ucs_size is zero, this argument is not be used.
+ *						\p ucs_size is zero, this argument is not be used.
  *	@param	ucs_size	The size, in number of UCS-2 characters, of the buffer
- *						pointed to by the \a ucs2str argument. If this value is
+ *						pointed to by the \p ucs2str argument. If this value is
  *						zero, the function returns the number of UCS-2
  *						characters required for the buffer.
  *	@param	mbstr		The pointer to the multi-byte characters to be
  *						converted.
  *	@param	mbs_size	The size, in bytes, of the multi-byte characters,
- *						\a mbstr.
+ *						\p mbstr.
  *	@param	charset		The pointer to the string specifying the encoding of
  *						the multi-byte characters.
- *	@retval	size_t		The number of UCS-2 characters written to \a ucs2str
- *						buffer if the conversion is successful. If \a ucs_size
+ *	@retval	size_t		The number of UCS-2 characters written to \p ucs2str
+ *						buffer if the conversion is successful. If \p ucs_size
  *						is zero, the return value is the required size, in
  *						number of UCS-2 characters, for a buffer to receive the
  *						converted string. This function returns zero if an error
  *						occurred.
  *	@note
- *		\a charset is ignored on Win32 environments.
+ *		\p charset is ignored on Win32 environments.
  */
 UCS2API size_t mbstoucs2_charset(ucs2char_t *ucs2str, size_t ucs_size, const char *mbstr, size_t mbs_size, const char *charset);
 
 /**
- * Convert a UCS-2 string to multi-byte characters.
+ * Convert a UCS-2 string to a UTF-8 string.
  *
- *	@param	mbstr		The pointer to the buffer for receiving UTF-8 string
- *						converted from the UCS-2 string. If	\a mbs_size is
+ *	@param	mbstr		The pointer to the buffer that receives UTF-8 string
+ *						converted from the UCS-2 string. If	\p mbs_size is
  *						zero, this argument is not be used.
  *	@param	mbs_size	The size, in bytes, of the buffer pointed to by the
- *						\a mbstr argument. If this value is zero, the function
+ *						\p mbstr argument. If this value is zero, the function
  *						returns the number of bytes required for the buffer.
  *	@param	ucs2str		The pointer to the UCS-2 string to be converted.
  *	@param	ucs_size	The size, in number of UCS-2 characters, of the UCS-2
- *						string, \a ucs2str.
- *	@retval	size_t		The number of bytes written to \a mbstr buffer if
- *						the conversion is successful. If \a mbs_size is zero,
+ *						string, \p ucs2str.
+ *	@retval	size_t		The number of bytes written to \p mbstr buffer if
+ *						the conversion is successful. If \p mbs_size is zero,
  *						the return value is the required size, in bytes, for a
  *						buffer to receive the converted string. This function
  *						returns zero if an error occurred.
@@ -225,17 +241,17 @@
 /**
  * Convert a UTF-8 string to a UCS-2 string.
  *
- *	@param	ucs2str		The pointer to the buffer for receiving UCS-2 string
- *						converted from the UTF-8 string. If	\a ucs_size is
+ *	@param	ucs2str		The pointer to the buffer that receives UCS-2 string
+ *						converted from the UTF-8 string. If	\p ucs_size is
  *						zero, this argument is not be used.
  *	@param	ucs_size	The size, in number of UCS-2 characters, of the buffer
- *						pointed to by the \a ucs2str argument. If this value is
+ *						pointed to by the \p ucs2str argument. If this value is
  *						zero, the function returns the number of UCS-2
  *						characters required for the buffer.
  *	@param	mbstr		The pointer to the UTF-8 string to be converted.
- *	@param	mbs_size	The size, in bytes, of the UTF-8 string, \a mbstr.
- *	@retval	size_t		The number of UCS-2 characters written to \a ucs2str
- *						buffer if the conversion is successful. If \a ucs_size
+ *	@param	mbs_size	The size, in bytes, of the UTF-8 string, \p mbstr.
+ *	@retval	size_t		The number of UCS-2 characters written to \p ucs2str
+ *						buffer if the conversion is successful. If \p ucs_size
  *						is zero, the return value is the required size, in
  *						number of UCS-2 characters, for a buffer to receive the
  *						converted string. This function returns zero if an error
@@ -285,7 +301,7 @@
 /**
  * Convert and duplicate a UTF-8 string to a UCS-2 string.
  *
- *	@param	mbstr		The pointer to multi-byte characters.
+ *	@param	utf8str		The pointer to a UTF-8 string.
  *	@retval	char*		The pointer to the duplicated string. Call ucs2free()
  *						to free the memory block allocated by this function.
  */
@@ -298,8 +314,11 @@
 
 
 /**
- * @defgroup ucs2_memory Memory manager routines
+ * @defgroup ucs2_memory Memory manager
  * @{ 
+ *
+ *	Memory manager provides functions to allocate/expand/free memory blocks.
+ *	Use these functions to manage memory blocks allocated by the PMPlib API.
  */
 
 /**
@@ -330,7 +349,7 @@
 /**
  * Free a memory block.
  *
- *	@param	ptr			The pointer to the memory block to be freed.
+ *	@param	ptr			The pointer to the memory block to be free.
  */
 UCS2API void ucs2free(void* ptr);
 
@@ -341,6 +360,9 @@
 /**
  * @defgroup ucs2_char UCS-2 character routines
  * @{ 
+ *
+ *	UCS-2 character routines provide the utility to classify characters and
+ *	convert from upper and lower cases.
  */
 
 /**
@@ -390,9 +412,9 @@
  * @defgroup ucs2_string_ansi ANSI C compatible string routines
  * @{ 
  *
- *	This is the subset of the UCS-2 Character/String API that corresponds
- *	to string manupulation routines in the ANSI C standard. The following
- *	ANSI C functions are not defined in this subset:
+ *	ANSI C compatible string routines correspond to string manupulation
+ *	routines in the ANSI C standard. The following ANSI C functions are not
+ *	defined in this API subset:
  *		strcoll, strerror, strtok, strxfrm.
  */
 
@@ -408,10 +430,10 @@
 /**
  * Search for the first occurrence of a character in a string.
  *
- *	@param	str			The pointer to the string in which \a c is searched.
+ *	@param	str			The pointer to the string in which \p c is searched.
  *	@param	c			The target character.
- *	@retval	ucs2char_t*	The pointer to the character \a c in \a str, or \c NULL
- *						if \a c does not occur in \a str.
+ *	@retval	ucs2char_t*	The pointer to the character \p c in \p str, or \c NULL
+ *						if \p c does not occur in \p str.
  */
 UCS2API ucs2char_t* ucs2chr(const ucs2char_t* str, ucs2char_t c);
 
@@ -420,9 +442,9 @@
  *
  *	@param	x			The pointer to a string.
  *	@param	y			The pointer to another string.
- *	@retval	int			A positive value if \a x is greater than \a y;
- *						a negative value if \a x is smaller than \a y;
- *						zero if \a x is identical to \a y.
+ *	@retval	int			A positive value if \p x is greater than \p y;
+ *						a negative value if \p x is smaller than \p y;
+ *						zero if \p x is identical to \p y.
  */
 UCS2API int ucs2cmp(const ucs2char_t* x, const ucs2char_t* y);
 
@@ -440,9 +462,9 @@
  *
  *	@param	str			The pointer to a string.
  *	@param	charset		The pointer to a character set.
- *	@retval	size_t		The number of characters from the beginning of \a str
- *						in which any character in \a charset appear for the
- *						first time, or the length of \a str if such a character
+ *	@retval	size_t		The number of characters from the beginning of \p str
+ *						in which any character in \p charset appear for the
+ *						first time, or the length of \p str if such a character
  *						does not exist.
  */
 UCS2API size_t ucs2cspn(const ucs2char_t *str, const ucs2char_t *charset);
@@ -451,7 +473,7 @@
  * Count the length of a string.
  *
  *	@param	str			The pointer to a string.
- *	@retval	size_t		The number of characters in \a str.
+ *	@retval	size_t		The number of characters in \p str.
  */
 UCS2API size_t ucs2len(const ucs2char_t* str);
 
@@ -471,9 +493,9 @@
  *	@param	x			The pointer to a string.
  *	@param	y			The pointer to another string.
  *	@param	n			The number of characters to be compared.
- *	@retval	int			A positive value if \a x is greater than \a y;
- *						a negative value if \a x is smaller than \a y;
- *						zero if \a x is identical to \a y.
+ *	@retval	int			A positive value if \p x is greater than \p y;
+ *						a negative value if \p x is smaller than \p y;
+ *						zero if \p x is identical to \p y.
  */
 UCS2API int ucs2ncmp(const ucs2char_t* x, const ucs2char_t* y, size_t n);
 
@@ -490,10 +512,10 @@
 /**
  * Find a character in a string that belongs to a character set.
  *
- *	@param	str			The pointer to the string where \a charset is searched.
+ *	@param	str			The pointer to the string where \p charset is searched.
  *	@param	charset		The pointer to a character set.
- *	@retval	ucs2char_t*	The pointer to the character in \a str that belongs
- *						to \a charset, or \c NULL if such a character does not
+ *	@retval	ucs2char_t*	The pointer to the character in \p str that belongs
+ *						to \p charset, or \c NULL if such a character does not
  *						exist.
  */
 UCS2API ucs2char_t* ucs2pbrk(const ucs2char_t *str, const ucs2char_t *charset);
@@ -501,20 +523,20 @@
 /**
  * Search for the last occurrence of a character in a string.
  *
- *	@param	str			The pointer to the string in which \a c is searched.
+ *	@param	str			The pointer to the string in which \p c is searched.
  *	@param	c			The target character.
- *	@retval	ucs2char_t*	The pointer to the character \a c in \a str, or \c NULL
- *						if \a c does not occur in \a str.
+ *	@retval	ucs2char_t*	The pointer to the character \p c in \p str, or \c NULL
+ *						if \p c does not occur in \p str.
  */
-UCS2API ucs2char_t* ucs2rchr(const ucs2char_t* string, ucs2char_t c);
+UCS2API ucs2char_t* ucs2rchr(const ucs2char_t* str, ucs2char_t c);
 
 /**
  * Find a character in a string that does not belong to a character set.
  *
- *	@param	str			The pointer to the string where \a charset is searched.
+ *	@param	str			The pointer to the string where \p charset is searched.
  *	@param	charset		The pointer to a character set.
- *	@retval	ucs2char_t*	The pointer to the character in \a str that does not
- *						belong to \a charset, or \c NULL if such a character
+ *	@retval	ucs2char_t*	The pointer to the character in \p str that does not
+ *						belong to \p charset, or \c NULL if such a character
  *						does not exist.
  */
 UCS2API size_t ucs2spn(const ucs2char_t *str, const ucs2char_t *charset);
@@ -522,11 +544,11 @@
 /**
  * Find a substring in a string.
  *
- *	@param	str			The pointer to the string where \a substr is searched.
+ *	@param	str			The pointer to the string where \p substr is searched.
  *	@param	substr		The pointer to the substring.
- *	@retval	ucs2char_t*	The pointer to the character where \a substr begins
- *						in \a str for the first time, or \c NULL if \a str
- *						does not contain \a substr.
+ *	@retval	ucs2char_t*	The pointer to the character where \p substr begins
+ *						in \p str for the first time, or \c NULL if \p str
+ *						does not contain \p substr.
  */
 UCS2API ucs2char_t* ucs2str(const ucs2char_t* str, const ucs2char_t* substr);
 
@@ -541,6 +563,8 @@
 /**
  * @defgroup ucs2_string_non_ansi Miscellaneous string routines
  * @{ 
+ *
+ *	Non ANSI C compatible string routines.
  */
 
 /**
@@ -560,31 +584,31 @@
  *	@retval	ucs2char_t*	The pointer to the duplicated string. Call ucs2free()
  *						to free the memory block allocated by this function.
  */
-UCS2API ucs2char_t* ucs2ndup(const ucs2char_t* src, size_t length);
+UCS2API ucs2char_t* ucs2ndup(const ucs2char_t* str, size_t length);
 
 /**
  * Convert a string to lowercase.
  *
- *	Given \a str argument, this function converts uppercase letters in the
+ *	Given \p str argument, this function converts uppercase letters in the
  *	string to lowercase and overwrites the resultant string on the same buffer
- *	pointed by the \a str argument.
+ *	pointed by the \p str argument.
  *
  *	@param	str			The pointer to a string. 
  *	@retval	ucs2char_t*	The pointer to the string, which is the same value as
- *						\a str.
+ *						\p str.
  */
 UCS2API ucs2char_t* ucs2lwr(ucs2char_t* str);
 
 /**
  * Convert a string to uppercase.
  *
- *	Given \a str argument, this function converts lowercase letters in the
+ *	Given \p str argument, this function converts lowercase letters in the
  *	string to uppercase and overwrites the resultant string on the same buffer
- *	pointed by the \a str argument.
+ *	pointed by the \p str argument.
  *
  *	@param	str			The pointer to a string. 
  *	@retval	ucs2char_t*	The pointer to the string, which is the same value as
- *						\a str.
+ *						\p str.
  */
 UCS2API ucs2char_t* ucs2upr(ucs2char_t* str);
 
@@ -593,9 +617,9 @@
  *
  *	@param	x			The pointer to a string.
  *	@param	y			The pointer to another string.
- *	@retval	int			A positive value if \a x is greater than \a y;
- *						a negative value if \a x is smaller than \a y;
- *						zero if \a x is identical to \a y.
+ *	@retval	int			A positive value if \p x is greater than \p y;
+ *						a negative value if \p x is smaller than \p y;
+ *						zero if \p x is identical to \p y.
  */
 UCS2API int ucs2icmp(const ucs2char_t* x, const ucs2char_t* y);
 
@@ -605,22 +629,22 @@
  *	@param	x			The pointer to a string.
  *	@param	y			The pointer to another string.
  *	@param	n			The number of characters to be compared.
- *	@retval	int			A positive value if \a x is greater than \a y;
- *						a negative value if \a x is smaller than \a y;
- *						zero if \a x is identical to \a y.
+ *	@retval	int			A positive value if \p x is greater than \p y;
+ *						a negative value if \p x is smaller than \p y;
+ *						zero if \p x is identical to \p y.
  */
 UCS2API int ucs2incmp(const ucs2char_t* x, const ucs2char_t* y, size_t n);
 
 /**
  * Strip whitespace characters at the head and tail of a string.
  *
- *	Given \a str argument, this function trims whilespace characters at the
+ *	Given \p str argument, this function trims whilespace characters at the
  *	head and tail of the string and overwrites the resultant string on the
- *	same buffer pointed by the \a str argument.
+ *	same buffer pointed by the \p str argument.
  *
  *	@param	str			The pointer to a string.
  *	@retval	ucs2char_t*	The pointer to the string, which is the same value as
- *						\a str.
+ *						\p str.
  */
 UCS2API ucs2char_t* ucs2strip(ucs2char_t* str);
 
@@ -631,8 +655,11 @@
 
 
 /**
- * @defgroup ucs2_std Wrapper for stdio/stdlib routines
+ * @defgroup ucs2_std ANSI C compatible stdio/stdlib routines
  * @{ 
+ *
+ *	ANSI C compatible stdio/stdlib routines provide utilities for streams and
+ *	string-integer conversions.
  */
 
 /**
@@ -646,9 +673,9 @@
  * Convert an integer value to UCS-2 string.
  *	@param	value		The integer value.
  *	@param	string		The pointer to the buffer to receive the string.
- *	@param	radix		Radix of the \a value.
+ *	@param	radix		Radix of the \p value.
  *	@retval	ucs2char_t*	The pointer to the string, which is the same value as
- *						\a str.
+ *						\p str.
  */
 UCS2API ucs2char_t* itoucs2(int value, ucs2char_t *string, int radix);
 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.