[PATCH] Numerous fixes to kernel-doc info in source files.
A variety of (mostly) innocuous fixes to the embedded kernel-doc content in
source files, including:
* make multi-line initial descriptions single line
* denote some function names, constants and structs as such
* change erroneous opening '/*' to '/**' in a few places
* reword some text for clarity
Signed-off-by: Robert P. J. Day <rpjday@mindspring.com>
Cc: "Randy.Dunlap" <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
diff --git a/lib/bitmap.c b/lib/bitmap.c
index 037fa9a..ee6e58f 100644
--- a/lib/bitmap.c
+++ b/lib/bitmap.c
@@ -95,7 +95,7 @@
}
EXPORT_SYMBOL(__bitmap_complement);
-/*
+/**
* __bitmap_shift_right - logical right shift of the bits in a bitmap
* @dst - destination bitmap
* @src - source bitmap
@@ -139,7 +139,7 @@
EXPORT_SYMBOL(__bitmap_shift_right);
-/*
+/**
* __bitmap_shift_left - logical left shift of the bits in a bitmap
* @dst - destination bitmap
* @src - source bitmap
@@ -529,7 +529,7 @@
}
EXPORT_SYMBOL(bitmap_parselist);
-/*
+/**
* bitmap_pos_to_ord(buf, pos, bits)
* @buf: pointer to a bitmap
* @pos: a bit position in @buf (0 <= @pos < @bits)
@@ -804,7 +804,7 @@
* @pos: beginning of bit region to release
* @order: region size (log base 2 of number of bits) to release
*
- * This is the complement to __bitmap_find_free_region and releases
+ * This is the complement to __bitmap_find_free_region() and releases
* the found region (by clearing it in the bitmap).
*
* No return value.
diff --git a/lib/cmdline.c b/lib/cmdline.c
index 8a5b530..f596c08 100644
--- a/lib/cmdline.c
+++ b/lib/cmdline.c
@@ -43,10 +43,10 @@
* comma as well.
*
* Return values:
- * 0 : no int in string
- * 1 : int found, no subsequent comma
- * 2 : int found including a subsequent comma
- * 3 : hyphen found to denote a range
+ * 0 - no int in string
+ * 1 - int found, no subsequent comma
+ * 2 - int found including a subsequent comma
+ * 3 - hyphen found to denote a range
*/
int get_option (char **str, int *pint)
diff --git a/lib/idr.c b/lib/idr.c
index 7185353..305117c 100644
--- a/lib/idr.c
+++ b/lib/idr.c
@@ -329,8 +329,8 @@
/**
* idr_remove - remove the given id and free it's slot
- * idp: idr handle
- * id: uniqueue key
+ * @idp: idr handle
+ * @id: unique key
*/
void idr_remove(struct idr *idp, int id)
{
diff --git a/lib/kobject.c b/lib/kobject.c
index c2917ffe..2782f49 100644
--- a/lib/kobject.c
+++ b/lib/kobject.c
@@ -97,11 +97,12 @@
}
/**
- * kobject_get_path - generate and return the path associated with a given kobj
- * and kset pair. The result must be freed by the caller with kfree().
+ * kobject_get_path - generate and return the path associated with a given kobj and kset pair.
*
* @kobj: kobject in question, with which to build the path
* @gfp_mask: the allocation type used to allocate the path
+ *
+ * The result must be freed by the caller with kfree().
*/
char *kobject_get_path(struct kobject *kobj, gfp_t gfp_mask)
{
diff --git a/lib/sha1.c b/lib/sha1.c
index 1cdabe3..4c45fd5 100644
--- a/lib/sha1.c
+++ b/lib/sha1.c
@@ -20,8 +20,8 @@
#define K3 0x8F1BBCDCL /* Rounds 40-59: sqrt(5) * 2^30 */
#define K4 0xCA62C1D6L /* Rounds 60-79: sqrt(10) * 2^30 */
-/*
- * sha_transform: single block SHA1 transform
+/**
+ * sha_transform - single block SHA1 transform
*
* @digest: 160 bit digest to update
* @data: 512 bits of data to hash
@@ -80,9 +80,8 @@
}
EXPORT_SYMBOL(sha_transform);
-/*
- * sha_init: initialize the vectors for a SHA1 digest
- *
+/**
+ * sha_init - initialize the vectors for a SHA1 digest
* @buf: vector to initialize
*/
void sha_init(__u32 *buf)
diff --git a/lib/sort.c b/lib/sort.c
index 488788b..9615678 100644
--- a/lib/sort.c
+++ b/lib/sort.c
@@ -27,7 +27,7 @@
} while (--size > 0);
}
-/*
+/**
* sort - sort an array of elements
* @base: pointer to data to sort
* @num: number of elements
diff --git a/lib/string.c b/lib/string.c
index a485d75..bab440f 100644
--- a/lib/string.c
+++ b/lib/string.c
@@ -160,7 +160,7 @@
* @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
+ * Note that in contrast to strncpy(), strncat() ensures the result is
* terminated.
*/
char *strncat(char *dest, const char *src, size_t count)
@@ -366,8 +366,7 @@
#ifndef __HAVE_ARCH_STRSPN
/**
- * strspn - Calculate the length of the initial substring of @s which only
- * contain letters in @accept
+ * 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
*/
@@ -394,8 +393,7 @@
#ifndef __HAVE_ARCH_STRCSPN
/**
- * strcspn - Calculate the length of the initial substring of @s which does
- * not contain letters in @reject
+ * strcspn - Calculate the length of the initial substring of @s which does not contain letters in @reject
* @s: The string to be searched
* @reject: The string to avoid
*/
diff --git a/lib/textsearch.c b/lib/textsearch.c
index 98bcadc..9e2a002 100644
--- a/lib/textsearch.c
+++ b/lib/textsearch.c
@@ -218,7 +218,7 @@
* Call textsearch_next() to retrieve subsequent matches.
*
* Returns the position of first occurrence of the pattern or
- * UINT_MAX if no occurrence was found.
+ * %UINT_MAX if no occurrence was found.
*/
unsigned int textsearch_find_continuous(struct ts_config *conf,
struct ts_state *state,
diff --git a/lib/vsprintf.c b/lib/vsprintf.c
index bed7229..44f0e33 100644
--- a/lib/vsprintf.c
+++ b/lib/vsprintf.c
@@ -247,12 +247,12 @@
* be generated for the given input, excluding the trailing
* '\0', as per ISO C99. If you want to have the exact
* number of characters written into @buf as return value
- * (not including the trailing '\0'), use vscnprintf. If the
+ * (not including the trailing '\0'), use vscnprintf(). If the
* return is greater than or equal to @size, the resulting
* string is truncated.
*
* Call this function if you are already dealing with a va_list.
- * You probably want snprintf instead.
+ * You probably want snprintf() instead.
*/
int vsnprintf(char *buf, size_t size, const char *fmt, va_list args)
{
@@ -509,7 +509,7 @@
* returns 0.
*
* Call this function if you are already dealing with a va_list.
- * You probably want scnprintf instead.
+ * You probably want scnprintf() instead.
*/
int vscnprintf(char *buf, size_t size, const char *fmt, va_list args)
{
@@ -577,11 +577,11 @@
* @args: Arguments for the format string
*
* The function returns the number of characters written
- * into @buf. Use vsnprintf or vscnprintf in order to avoid
+ * into @buf. Use vsnprintf() or vscnprintf() in order to avoid
* buffer overflows.
*
* Call this function if you are already dealing with a va_list.
- * You probably want sprintf instead.
+ * You probably want sprintf() instead.
*/
int vsprintf(char *buf, const char *fmt, va_list args)
{
@@ -597,7 +597,7 @@
* @...: Arguments for the format string
*
* The function returns the number of characters written
- * into @buf. Use snprintf or scnprintf in order to avoid
+ * into @buf. Use snprintf() or scnprintf() in order to avoid
* buffer overflows.
*/
int sprintf(char * buf, const char *fmt, ...)