[PATCH 2/2] Add some documentation.

[max at mtew.isa-geek.net]

From: Max TenEyck Woodbury <max at mtew.isa-geek.net>

---
 dlls/msvcrt/string.c |  122 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 117 insertions(+), 5 deletions(-)

diff --git a/dlls/msvcrt/string.c b/dlls/msvcrt/string.c
index 031c3d0..bcbcb4a 100644
--- a/dlls/msvcrt/string.c
+++ b/dlls/msvcrt/string.c
@@ -38,6 +38,14 @@ WINE_DEFAULT_DEBUG_CHANNEL(msvcrt);
 /*********************************************************************
  *		_mbsdup (MSVCRT.@)
  *		_strdup (MSVCRT.@)
+ *
+ * Make a copy of a '\0' terminated string.
+ *
+ * PARAMS
+ *   str - [I] address the string to be copied.
+ * RETURNS
+ *   Success: a copy of str.
+ *   Failure: NULL.
  */
 char* CDECL _strdup(const char* str)
 {
@@ -52,6 +60,15 @@ char* CDECL _strdup(const char* str)
 
 /*********************************************************************
  *		_strlwr_s (MSVCRT.@)
+ *
+ * Safe convert string to lower case.
+ *
+ * PARAMS
+ *   str - [I/O] address of the string to be converted to lower case.
+ *   len - [I] the maximum length of the string.
+ * RETURNS
+ *   Success: 0.
+ *   Failure: MSVCRT_EINVAL. 
  */
 int CDECL _strlwr_s(char *str, MSVCRT_size_t len)
 {
@@ -87,6 +104,15 @@ int CDECL _strlwr_s(char *str, MSVCRT_size_t len)
 
 /*********************************************************************
  *		_strnset (MSVCRT.@)
+ *
+ * Replace the contents of a part of a string with a specific character.
+ *
+ * PARAMS
+ *   str   - [I/O] address of the string to be changed.
+ *   value - [I] the replacement character.
+ *   len   - [I] the maximum number of characters to be replaced.
+ * RETURNS
+ *   str.
  */
 char* CDECL MSVCRT__strnset(char* str, int value, MSVCRT_size_t len)
 {
@@ -98,6 +124,13 @@ char* CDECL MSVCRT__strnset(char* str, int value, MSVCRT_size_t len)
 
 /*********************************************************************
  *		_strrev (MSVCRT.@)
+ *
+ * Reverse the order of the characters in a string.
+ *
+ * PARAMS
+ *   str - [I/O] address of the string to be changed.
+ * RETURNS
+ *   str.
  */
 char* CDECL _strrev(char* str)
 {
@@ -117,6 +150,14 @@ char* CDECL _strrev(char* str)
 
 /*********************************************************************
  *		_strset (MSVCRT.@)
+ *
+ * Replace the contents of a string with a specific character.
+ *
+ * PARAMS
+ *   str   - [I/O] address of the string to be changed.
+ *   value - [I] the replacement value
+ * RETURNS
+ *   str.
  */
 char* CDECL _strset(char* str, int value)
 {
@@ -129,6 +170,17 @@ char* CDECL _strset(char* str, int value)
 
 /*********************************************************************
  *		strtok  (MSVCRT.@)
+ *
+ * Break a string into tokens with implicit context.
+ *
+ * PARAMS
+ *   str               - [I/O] address of string to be tokenized or NULL
+ *                       to continue the previous tokenization.
+ *   delim             - [I] address of the delimiters string.
+ *   data->strtok_next - [I/O] thread local scan context.
+ * RETURNS
+ *   Success: The address in the original str of the token found.
+ *   Failure: NULL.
  */
 char * CDECL MSVCRT_strtok( char *str, const char *delim )
 {
@@ -149,6 +201,17 @@ char * CDECL MSVCRT_strtok( char *str, const char *delim )
 
 /*********************************************************************
  *		strtok_s  (MSVCRT.@)
+ *
+ * Safe version of break a string into tokens with explicit context.
+ *
+ * PARAMS
+ *   str   - [I/O] address of string to be tokenized or NULL to continue
+ *           the previous tokenization.
+ *   delim - [I]  address of the delimiters string.
+ *   ctx   - [I/O] address of the context pointer.
+ * RETURNS
+ *   Success: The address in the original str of the token found.
+ *   Failure: NULL.
  */
 char * CDECL MSVCRT_strtok_s(char *str, const char *delim, char **ctx)
 {
@@ -177,6 +240,15 @@ char * CDECL MSVCRT_strtok_s(char *str, const char *delim, char **ctx)
 
 /*********************************************************************
  *		_swab (MSVCRT.@)
+ *
+ * Swap memory contents byte by byte.
+ *
+ * PARAMS
+ *   src - address of one memory area.
+ *   dst - address of the other memory area.
+ *   len - the number of bytes to exchange.
+ * RETURNS
+ *   nothing.
  */
 void CDECL MSVCRT__swab(char* src, char* dst, int len)
 {
@@ -196,6 +268,13 @@ void CDECL MSVCRT__swab(char* src, char* dst, int len)
 
 /*********************************************************************
  *		strtod_l  (MSVCRT.@)
+ *
+ * Convert a string to double using delimiters from locale with end point recorded.
+ *
+ * PARAMS
+ *   str    - [I] address of the string to be converted.
+ *   end    - [O] address of the end of scan pointer or NULL.
+ *   locale - [I] the locale for delimiters or NULL to use the current locale.
  */
 double CDECL MSVCRT_strtod_l( const char *str, char **end, MSVCRT__locale_t locale)
 {
@@ -310,6 +389,14 @@ double CDECL MSVCRT_strtod_l( const char *str, char **end, MSVCRT__locale_t loca
 
 /*********************************************************************
  *		strtod  (MSVCRT.@)
+ *
+ * String to double with end point recorded.
+ *
+ * PARAMS
+ *   str - [I] address of the string to be converted.
+ *   end - [O] address of the end of scan pointer or NULL.
+ * RETURNS
+ *   converted value as double.
  */
 double CDECL MSVCRT_strtod( const char *str, char **end )
 {
@@ -318,6 +405,13 @@ double CDECL MSVCRT_strtod( const char *str, char **end )
 
 /*********************************************************************
  *		atof  (MSVCRT.@)
+ *
+ * String to double.
+ *
+ * PARAMS
+ *   str - [I] address of the string to be converted.
+ * RETURNS
+ *   converted value as double.
  */
 double CDECL MSVCRT_atof( const char *str )
 {
@@ -326,6 +420,14 @@ double CDECL MSVCRT_atof( const char *str )
 
 /*********************************************************************
  *		_atof_l  (MSVCRT.@)
+ *
+ * String to double with delimiters from locale.
+ *
+ * PARAMS
+ *   str    - [I] address of the string to be converted.
+ *   locale - [I] the locale for delimiters or NULL to use the current locale.
+ * RETURNS
+ *   converted value as double.
  */
 double CDECL MSVCRT__atof_l( const char *str, MSVCRT__locale_t locale)
 {
@@ -648,6 +750,14 @@ MSVCRT_ulong CDECL MSVCRT_strtoul(const char* nptr, char** end, int base)
 
 /******************************************************************
  *              strnlen (MSVCRT.@)
+ *
+ * Get the limited length of a string.
+ *
+ * PARAMS
+ *   str    - [I] address of the string.
+ *   maxlen - [I] manimum value.
+ * RETURNS
+ *   length of str or maxlen.
  */
 MSVCRT_size_t CDECL MSVCRT_strnlen(const char *s, MSVCRT_size_t maxlen)
 {
@@ -1281,12 +1391,14 @@ struct _I10_OUTPUT_DATA {
 
 /*********************************************************************
  *              $I10_OUTPUT (MSVCRT.@)
- * ld - long double to be printed to data
- * prec - precision of part, we're interested in
- * flag - 0 for first prec digits, 1 for fractional part
- * data - data to be populated
  *
- * return value
+ * PARAMS
+ *   ld   - long double to be printed to data
+ *   prec - precision of part, we're interested in
+ *   flag - 0 for first prec digits, 1 for fractional part
+ *   data - output data structure to be populated
+ *
+ * RETURNS
  *      0 if given double is NaN or INF
  *      1 otherwise
  *
-- 
1.7.4