[PATCH] kernel-doc: fix function name in usercopy.c

[PATCH] kernel-doc: fix function name in usercopy.c

[Randy Dunlap]

From: Randy Dunlap <rdunlap@xenotime.net>

Fix kernel-doc function name in usercopy.c.

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
---
 arch/i386/lib/usercopy.c |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

--- linux-2619-rc1g3.orig/arch/i386/lib/usercopy.c
+++ linux-2619-rc1g3/arch/i386/lib/usercopy.c
@@ -179,7 +179,7 @@ __clear_user(void __user *to, unsigned l
 EXPORT_SYMBOL(__clear_user);
 
 /**
- * strlen_user: - Get the size of a string in user space.
+ * strnlen_user: - Get the size of a string in user space.
  * @s: The string to measure.
  * @n: The maximum valid length
  *


---

Re: [PATCH] kernel-doc: fix function name in usercopy.c

[Alexey Dobriyan]

On Sun, Oct 08, 2006 at 07:44:29PM -0700, Randy Dunlap wrote:
>  /**
> - * strlen_user: - Get the size of a string in user space.
> + * strnlen_user: - Get the size of a string in user space.

It's better to not spend time fixing mismatches, but to teach kernel-doc
extract function name from function itself.

	/**
	 * Get the size of a string in user space.
	 * @foo: bar
	 */
	 size_t strnlen_user()

Re: [PATCH] kernel-doc: fix function name in usercopy.c

[Randy Dunlap]

On Mon, 9 Oct 2006 07:28:51 +0400 Alexey Dobriyan wrote:

> On Sun, Oct 08, 2006 at 07:44:29PM -0700, Randy Dunlap wrote:
> >  /**
> > - * strlen_user: - Get the size of a string in user space.
> > + * strnlen_user: - Get the size of a string in user space.
> 
> It's better to not spend time fixing mismatches, but to teach kernel-doc
> extract function name from function itself.
> 
> 	/**
> 	 * Get the size of a string in user space.
> 	 * @foo: bar
> 	 */
> 	 size_t strnlen_user()

OK, maybe a good idea.  I'll add that to the wish list.
However, we have seen examples of:

/**
 * doc for foo
 */
int foo(int arg)
{
}

then someone inserts a new function bar() between the kernel-doc
and foo().  How would we catch that (automated)?
other than by our review process?

---
~Randy

Re: [PATCH] kernel-doc: fix function name in usercopy.c

[Rolf Eike Beer]

[-- Attachment #1: Type: text/plain, Size: 1004 bytes --]

Randy Dunlap wrote:
> On Mon, 9 Oct 2006 07:28:51 +0400 Alexey Dobriyan wrote:
> > On Sun, Oct 08, 2006 at 07:44:29PM -0700, Randy Dunlap wrote:
> > >  /**
> > > - * strlen_user: - Get the size of a string in user space.
> > > + * strnlen_user: - Get the size of a string in user space.
> >
> > It's better to not spend time fixing mismatches, but to teach kernel-doc
> > extract function name from function itself.
> >
> > 	/**
> > 	 * Get the size of a string in user space.
> > 	 * @foo: bar
> > 	 */
> > 	 size_t strnlen_user()
>
> OK, maybe a good idea.  I'll add that to the wish list.
> However, we have seen examples of:
>
> /**
>  * doc for foo
>  */
> int foo(int arg)
> {
> }
>
> then someone inserts a new function bar() between the kernel-doc
> and foo().  How would we catch that (automated)?
> other than by our review process?

Warn if the function signature of the documented function does not match the 
function and throw away the manpage then.

Eike

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]