[PATCH] Add documentation for string functions

[PATCH] Add documentation for string functions

[Matthew Wilcox]

diff -urNX dontdiff linux-2.4.2/Documentation/DocBook/Makefile linux-willy/Documentation/DocBook/Makefile
--- linux-2.4.2/Documentation/DocBook/Makefile	Sat Feb  3 13:43:55 2001
+++ linux-willy/Documentation/DocBook/Makefile	Sat Mar  3 18:01:07 2001
@@ -82,6 +82,8 @@
 		$(TOPDIR)/kernel/pm.c \
 		$(TOPDIR)/kernel/ksyms.c \
 		$(TOPDIR)/kernel/kmod.c \
+		$(TOPDIR)/lib/string.c \
+		$(TOPDIR)/lib/vsprintf.c \
 		$(TOPDIR)/net/netsyms.c
  
 kernel-api.sgml: kernel-api.tmpl $(APISOURCES)
diff -urNX dontdiff linux-2.4.2/Documentation/DocBook/kernel-api.tmpl linux-willy/Documentation/DocBook/kernel-api.tmpl
--- linux-2.4.2/Documentation/DocBook/kernel-api.tmpl	Sat Dec 30 19:16:13 2000
+++ linux-willy/Documentation/DocBook/kernel-api.tmpl	Sat Mar  3 18:00:33 2001
@@ -41,6 +41,16 @@
      </sect1>
   </chapter>
 
+  <chapter id="libc">
+     <title>Basic C Library Functions</title>
+     <sect1><title>String Conversions</title>
+!Ilib/vsprintf.c
+     </sect1>
+     <sect1><title>String Manipulation</title>
+!Ilib/string.c
+     </sect1>
+  </chapter>
+
   <chapter id="mm">
      <title>Memory Management in Linux</title>
      <sect1><title>The Slab Cache</title>
diff -urNX dontdiff linux-2.4.2/lib/string.c linux-willy/lib/string.c
--- linux-2.4.2/lib/string.c	Thu Aug 10 14:10:14 2000
+++ linux-willy/lib/string.c	Sat Mar  3 19:56:04 2001
@@ -20,6 +20,12 @@
 #include <linux/ctype.h>
 
 #ifndef __HAVE_ARCH_STRNICMP
+/**
+ * strnicmp - Case insensitive, length-limited string comparison
+ * @s1: One string
+ * @s2: The other string
+ * @len: the maximum number of characters to compare
+ */
 int strnicmp(const char *s1, const char *s2, size_t len)
 {
 	/* Yes, Virginia, it had better be unsigned */
@@ -49,6 +55,11 @@
 char * ___strtok;
 
 #ifndef __HAVE_ARCH_STRCPY
+/**
+ * strcpy - Copy a %NUL terminated string
+ * @dest: Where to copy the string to
+ * @src: Where to copy the string from
+ */
 char * strcpy(char * dest,const char *src)
 {
 	char *tmp = dest;
@@ -60,6 +71,16 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRNCPY
+/**
+ * strncpy - Copy a length-limited, %NUL-terminated string
+ * @dest: Where to copy the string to
+ * @src: Where to copy the string from
+ * @count: The maximum number of bytes to copy
+ *
+ * Note that unlike userspace strncpy, this does not %NUL-pad the buffer.
+ * However, the result is not %NUL-terminated if the source exceeds
+ * @count bytes.
+ */
 char * strncpy(char * dest,const char *src,size_t count)
 {
 	char *tmp = dest;
@@ -72,6 +93,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRCAT
+/**
+ * strcat - Append one %NUL-terminated string to another
+ * @dest: The string to be appended to
+ * @src: The string to append to it
+ */
 char * strcat(char * dest, const char * src)
 {
 	char *tmp = dest;
@@ -86,6 +112,15 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRNCAT
+/**
+ * strncat - Append a length-limited, %NUL-terminated string to another
+ * @dest: The string to be appended to
+ * @src: The string to append to it
+ * @count: The maximum numbers of bytes to copy
+ *
+ * Note that in contrast to strncpy, strncat ensures the result is
+ * terminated.
+ */
 char * strncat(char *dest, const char *src, size_t count)
 {
 	char *tmp = dest;
@@ -106,6 +141,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRCMP
+/**
+ * strcmp - Compare two strings
+ * @cs: One string
+ * @ct: Another string
+ */
 int strcmp(const char * cs,const char * ct)
 {
 	register signed char __res;
@@ -120,6 +160,12 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRNCMP
+/**
+ * strncmp - Compare two length-limited strings
+ * @cs: One string
+ * @ct: Another string
+ * @count: The maximum number of bytes to compare
+ */
 int strncmp(const char * cs,const char * ct,size_t count)
 {
 	register signed char __res = 0;
@@ -135,6 +181,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRCHR
+/**
+ * strchr - Find the first occurrence of a character in a string
+ * @s: The string to be searched
+ * @c: The character to search for
+ */
 char * strchr(const char * s, int c)
 {
 	for(; *s != (char) c; ++s)
@@ -145,6 +196,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRRCHR
+/**
+ * strrchr - Find the last occurrence of a character in a string
+ * @s: The string to be searched
+ * @c: The character to search for
+ */
 char * strrchr(const char * s, int c)
 {
        const char *p = s + strlen(s);
@@ -157,6 +213,10 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRLEN
+/**
+ * strlen - Find the length of a string
+ * @s: The string to be sized
+ */
 size_t strlen(const char * s)
 {
 	const char *sc;
@@ -168,6 +228,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRNLEN
+/**
+ * strnlen - Find the length of a length-limited string
+ * @s: The string to be sized
+ * @count: The maximum number of bytes to search
+ */
 size_t strnlen(const char * s, size_t count)
 {
 	const char *sc;
@@ -179,6 +244,12 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRSPN
+/**
+ * strspn - Calculate the length of the initial substring of @s which only
+ * 	contain letters in @accept
+ * @s: The string to be searched
+ * @accept: The string to search for
+ */
 size_t strspn(const char *s, const char *accept)
 {
 	const char *p;
@@ -200,6 +271,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRPBRK
+/**
+ * strpbrk - Find the first occurrence of a set of characters
+ * @cs: The string to be searched
+ * @ct: The characters to search for
+ */
 char * strpbrk(const char * cs,const char * ct)
 {
 	const char *sc1,*sc2;
@@ -215,6 +291,13 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRTOK
+/**
+ * strtok - Split a string into tokens
+ * @s: The string to be searched
+ * @ct: The characters to search for
+ *
+ * WARNING: strtok is deprecated, use strsep instead.
+ */
 char * strtok(char * s,const char * ct)
 {
 	char *sbegin, *send;
@@ -237,7 +320,13 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRSEP
-
+/**
+ * strsep - Split a string into tokens
+ * @s: The string to be searched
+ * @ct: The characters to search for
+ *
+ * strsep() updates @s to point after the token, ready for the next call.
+ */
 char * strsep(char **s, const char * ct)
 {
 	char *sbegin=*s;
@@ -256,6 +345,12 @@
 #endif
 
 #ifndef __HAVE_ARCH_MEMSET
+/**
+ * memset - Fill a region of memory with the given value
+ * @s: Pointer to the start of the area.
+ * @c: The byte to fill the area with
+ * @count: The size of the area.
+ */
 void * memset(void * s,int c,size_t count)
 {
 	char *xs = (char *) s;
@@ -268,6 +363,12 @@
 #endif
 
 #ifndef __HAVE_ARCH_BCOPY
+/**
+ * bcopy - Copy one area of memory to another
+ * @src: Where to copy from
+ * @dest: Where to copy to
+ * @count: The size of the area.
+ */
 char * bcopy(const char * src, char * dest, int count)
 {
 	char *tmp = dest;
@@ -280,6 +381,14 @@
 #endif
 
 #ifndef __HAVE_ARCH_MEMCPY
+/**
+ * memcpy - Copy one area of memory to another
+ * @dest: Where to copy to
+ * @src: Where to copy from
+ * @count: The size of the area.
+ *
+ * Note that this is the same as bcopy, with the arguments reversed.
+ */
 void * memcpy(void * dest,const void *src,size_t count)
 {
 	char *tmp = (char *) dest, *s = (char *) src;
@@ -292,6 +401,14 @@
 #endif
 
 #ifndef __HAVE_ARCH_MEMMOVE
+/**
+ * memmove - Copy one area of memory to another
+ * @dest: Where to copy to
+ * @src: Where to copy from
+ * @count: The size of the area.
+ *
+ * memmove copes with overlapping areas.
+ */
 void * memmove(void * dest,const void *src,size_t count)
 {
 	char *tmp, *s;
@@ -314,6 +431,12 @@
 #endif
 
 #ifndef __HAVE_ARCH_MEMCMP
+/**
+ * memmove - Compare two areas of memory
+ * @cs: One area of memory
+ * @ct: Another area of memory
+ * @count: The size of the area.
+ */
 int memcmp(const void * cs,const void * ct,size_t count)
 {
 	const unsigned char *su1, *su2;
@@ -326,10 +449,16 @@
 }
 #endif
 
-/*
- * find the first occurrence of byte 'c', or 1 past the area if none
- */
 #ifndef __HAVE_ARCH_MEMSCAN
+/**
+ * memscan - Find a character in an area of memory.
+ * @addr: The memory area
+ * @c: The byte to search for
+ * @size: The size of the area.
+ *
+ * returns the address of the first occurrence of @c, or 1 byte past
+ * the area if @c is not found
+ */
 void * memscan(void * addr, int c, size_t size)
 {
 	unsigned char * p = (unsigned char *) addr;
@@ -345,6 +474,11 @@
 #endif
 
 #ifndef __HAVE_ARCH_STRSTR
+/**
+ * strstr - Find the first substring in a %NUL terminated string
+ * @s1: The string to be searched
+ * @s2: The string to search for
+ */
 char * strstr(const char * s1,const char * s2)
 {
 	int l1, l2;
@@ -364,6 +498,15 @@
 #endif
 
 #ifndef __HAVE_ARCH_MEMCHR
+/**
+ * memchr - Find a character in an area of memory.
+ * @s: The memory area
+ * @c: The byte to search for
+ * @n: The size of the area.
+ *
+ * returns the address of the first occurrence of @c, or %NULL
+ * if @c is not found
+ */
 void *memchr(const void *s, int c, size_t n)
 {
 	const unsigned char *p = s;
diff -urNX dontdiff linux-2.4.2/lib/vsprintf.c linux-willy/lib/vsprintf.c
--- linux-2.4.2/lib/vsprintf.c	Mon Nov 27 18:44:26 2000
+++ linux-willy/lib/vsprintf.c	Sat Mar  3 17:54:18 2001
@@ -16,6 +16,12 @@
 
 #include <asm/div64.h>
 
+/**
+ * simple_strtoul - convert a string to an unsigned long
+ * @cp: The start of the string
+ * @endp: A pointer to the end of the parsed string will be placed here
+ * @base: The number base to use
+ */
 unsigned long simple_strtoul(const char *cp,char **endp,unsigned int base)
 {
 	unsigned long result = 0,value;
@@ -41,6 +47,12 @@
 	return result;
 }
 
+/**
+ * simple_strtol - convert a string to a signed long
+ * @cp: The start of the string
+ * @endp: A pointer to the end of the parsed string will be placed here
+ * @base: The number base to use
+ */
 long simple_strtol(const char *cp,char **endp,unsigned int base)
 {
 	if(*cp=='-')
@@ -48,6 +60,12 @@
 	return simple_strtoul(cp,endp,base);
 }
 
+/**
+ * simple_strtoull - convert a string to an unsigned long long
+ * @cp: The start of the string
+ * @endp: A pointer to the end of the parsed string will be placed here
+ * @base: The number base to use
+ */
 unsigned long long simple_strtoull(const char *cp,char **endp,unsigned int base)
 {
 	unsigned long long result = 0,value;
@@ -73,6 +91,12 @@
 	return result;
 }
 
+/**
+ * simple_strtoll - convert a string to a signed long long
+ * @cp: The start of the string
+ * @endp: A pointer to the end of the parsed string will be placed here
+ * @base: The number base to use
+ */
 long long simple_strtoll(const char *cp,char **endp,unsigned int base)
 {
 	if(*cp=='-')
@@ -163,9 +187,15 @@
 	return str;
 }
 
-/* Forward decl. needed for IP address printing stuff... */
-int sprintf(char * buf, const char *fmt, ...);
-
+/**
+ * vsprintf - Format a string and place it in a buffer
+ * @buf: The buffer to place the result into
+ * @fmt: The format string to use
+ * @args: Arguments for the format string
+ *
+ * Call this function if you are already dealing with a va_list.
+ * You probably want sprintf instead.
+ */
 int vsprintf(char *buf, const char *fmt, va_list args)
 {
 	int len;
@@ -343,6 +373,12 @@
 	return str-buf;
 }
 
+/**
+ * sprintf - Format a string and place it in a buffer
+ * @buf: The buffer to place the result into
+ * @fmt: The format string to use
+ * @args: Arguments for the format string
+ */
 int sprintf(char * buf, const char *fmt, ...)
 {
 	va_list args;