[PATCH] Add kerneldoc documentation for new printk format extensions

[PATCH] Add kerneldoc documentation for new printk format extensions

[Andi Kleen]

Add documentation in kerneldoc for new printk format extensions

This patch documents the new %pS/%pF options in printk in kernel doc.

Hope I didn't miss any other extension.

Signed-off-by: Andi Kleen <ak@linux.intel.com>

Index: linux-2.6.27-rc6-misc/kernel/printk.c
===================================================================
--- linux-2.6.27-rc6-misc.orig/kernel/printk.c
+++ linux-2.6.27-rc6-misc/kernel/printk.c
@@ -593,6 +593,8 @@ static int have_callable_console(void)
  *
  * See also:
  * printf(3)
+ *
+ * See the vsnprintf() documentation for format string extensions over C99.
  */
 
 asmlinkage int printk(const char *fmt, ...)
Index: linux-2.6.27-rc6-misc/lib/vsprintf.c
===================================================================
--- linux-2.6.27-rc6-misc.orig/lib/vsprintf.c
+++ linux-2.6.27-rc6-misc/lib/vsprintf.c
@@ -565,6 +565,10 @@ static char *pointer(const char *fmt, ch
  * @fmt: The format string to use
  * @args: Arguments for the format string
  *
+ * This function follows C99 vsnprintf, but has some extensions:
+ * %pS output the name of a text symbol
+ * %pF output the name of a function pointer
+ *
  * The return value is the number of characters which would
  * be generated for the given input, excluding the trailing
  * '\0', as per ISO C99. If you want to have the exact
@@ -806,6 +810,8 @@ EXPORT_SYMBOL(vsnprintf);
  *
  * Call this function if you are already dealing with a va_list.
  * You probably want scnprintf() instead.
+ *
+ * See the vsnprintf() documentation for format string extensions over C99.
  */
 int vscnprintf(char *buf, size_t size, const char *fmt, va_list args)
 {
@@ -828,6 +834,8 @@ EXPORT_SYMBOL(vscnprintf);
  * generated for the given input, excluding the trailing null,
  * as per ISO C99.  If the return is greater than or equal to
  * @size, the resulting string is truncated.
+ *
+ * See the vsnprintf() documentation for format string extensions over C99.
  */
 int snprintf(char * buf, size_t size, const char *fmt, ...)
 {
@@ -877,6 +885,8 @@ EXPORT_SYMBOL(scnprintf);
  *
  * Call this function if you are already dealing with a va_list.
  * You probably want sprintf() instead.
+ *
+ * See the vsnprintf() documentation for format string extensions over C99.
  */
 int vsprintf(char *buf, const char *fmt, va_list args)
 {
@@ -894,6 +904,8 @@ EXPORT_SYMBOL(vsprintf);
  * The function returns the number of characters written
  * into @buf. Use snprintf() or scnprintf() in order to avoid
  * buffer overflows.
+ *
+ * See the vsnprintf() documentation for format string extensions over C99.
  */
 int sprintf(char * buf, const char *fmt, ...)
 {

Re: [PATCH] Add kerneldoc documentation for new printk format extensions

[Américo Wang]

On Tue, Oct 07, 2008 at 12:15:32PM +0200, Andi Kleen wrote:
>Add documentation in kerneldoc for new printk format extensions
>
>This patch documents the new %pS/%pF options in printk in kernel doc.
>
>Hope I didn't miss any other extension.
>
>Signed-off-by: Andi Kleen <ak@linux.intel.com>
>
>Index: linux-2.6.27-rc6-misc/kernel/printk.c
>===================================================================
>--- linux-2.6.27-rc6-misc.orig/kernel/printk.c
>+++ linux-2.6.27-rc6-misc/kernel/printk.c
>@@ -593,6 +593,8 @@ static int have_callable_console(void)
>  *
>  * See also:
>  * printf(3)
>+ *
>+ * See the vsnprintf() documentation for format string extensions over C99.
>  */
> 
> asmlinkage int printk(const char *fmt, ...)
>Index: linux-2.6.27-rc6-misc/lib/vsprintf.c
>===================================================================
>--- linux-2.6.27-rc6-misc.orig/lib/vsprintf.c
>+++ linux-2.6.27-rc6-misc/lib/vsprintf.c
>@@ -565,6 +565,10 @@ static char *pointer(const char *fmt, ch
>  * @fmt: The format string to use
>  * @args: Arguments for the format string
>  *
>+ * This function follows C99 vsnprintf, but has some extensions:
>+ * %pS output the name of a text symbol
>+ * %pF output the name of a function pointer

s/output/outputs/ ? :)


-- 
"Sometimes the only way to stay sane is to go a little crazy."

Re: [PATCH] Add kerneldoc documentation for new printk format extensions

[Andi Kleen]

On Tue, Oct 07, 2008 at 11:33:05AM +0100, Américo Wang wrote:
> On Tue, Oct 07, 2008 at 12:15:32PM +0200, Andi Kleen wrote:
> >Add documentation in kerneldoc for new printk format extensions
> >
> >This patch documents the new %pS/%pF options in printk in kernel doc.
> >
> >Hope I didn't miss any other extension.
> >
> >Signed-off-by: Andi Kleen <ak@linux.intel.com>
> >
> >Index: linux-2.6.27-rc6-misc/kernel/printk.c
> >===================================================================
> >--- linux-2.6.27-rc6-misc.orig/kernel/printk.c
> >+++ linux-2.6.27-rc6-misc/kernel/printk.c
> >@@ -593,6 +593,8 @@ static int have_callable_console(void)
> >  *
> >  * See also:
> >  * printf(3)
> >+ *
> >+ * See the vsnprintf() documentation for format string extensions over C99.
> >  */
> > 
> > asmlinkage int printk(const char *fmt, ...)
> >Index: linux-2.6.27-rc6-misc/lib/vsprintf.c
> >===================================================================
> >--- linux-2.6.27-rc6-misc.orig/lib/vsprintf.c
> >+++ linux-2.6.27-rc6-misc/lib/vsprintf.c
> >@@ -565,6 +565,10 @@ static char *pointer(const char *fmt, ch
> >  * @fmt: The format string to use
> >  * @args: Arguments for the format string
> >  *
> >+ * This function follows C99 vsnprintf, but has some extensions:
> >+ * %pS output the name of a text symbol
> >+ * %pF output the name of a function pointer
> 
> s/output/outputs/ ? :)

It's not complete sentences but a list of options, so no.

bla do this
blub do that

-Andi

-- 
ak@linux.intel.com

Re: [PATCH] Add kerneldoc documentation for new printk format extensions

[Randy.Dunlap]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1830 bytes --]

On Tue, 7 Oct 2008, Andi Kleen wrote:

> On Tue, Oct 07, 2008 at 11:33:05AM +0100, Américo Wang wrote:
> > On Tue, Oct 07, 2008 at 12:15:32PM +0200, Andi Kleen wrote:
> > >Add documentation in kerneldoc for new printk format extensions
> > >
> > >This patch documents the new %pS/%pF options in printk in kernel doc.
> > >
> > >Hope I didn't miss any other extension.
> > >
> > >Signed-off-by: Andi Kleen <ak@linux.intel.com>
> > >
> > >Index: linux-2.6.27-rc6-misc/kernel/printk.c
> > >===================================================================
> > >--- linux-2.6.27-rc6-misc.orig/kernel/printk.c
> > >+++ linux-2.6.27-rc6-misc/kernel/printk.c
> > >@@ -593,6 +593,8 @@ static int have_callable_console(void)
> > >  *
> > >  * See also:
> > >  * printf(3)
> > >+ *
> > >+ * See the vsnprintf() documentation for format string extensions over C99.
> > >  */
> > > 
> > > asmlinkage int printk(const char *fmt, ...)
> > >Index: linux-2.6.27-rc6-misc/lib/vsprintf.c
> > >===================================================================
> > >--- linux-2.6.27-rc6-misc.orig/lib/vsprintf.c
> > >+++ linux-2.6.27-rc6-misc/lib/vsprintf.c
> > >@@ -565,6 +565,10 @@ static char *pointer(const char *fmt, ch
> > >  * @fmt: The format string to use
> > >  * @args: Arguments for the format string
> > >  *
> > >+ * This function follows C99 vsnprintf, but has some extensions:
> > >+ * %pS output the name of a text symbol
> > >+ * %pF output the name of a function pointer
> > 
> > s/output/outputs/ ? :)
> 
> It's not complete sentences but a list of options, so no.
> 
> bla do this
> blub do that

I would use "outputs" _or_ separate the format string extension from the
description, like:

 * %pS: output the name of a text symbol

Anyway, thanks for adding them.
-- 
~Randy