kernel-doc problem

kernel-doc problem

[Johannes Berg]

Randy, all,

I'm running into a problem where something that I want to be part of a
description of a struct member or function parameter gets parsed as a
new section. You can easily see the problem by running below test file
through kernel-doc, clearly the intent is not to have a new section in
the middle of function argument descriptions, but I have no idea how I
could fix this.

I'd appreciate if you could take a look.

Thanks,
Johannes

--- here's the file ---
/**
 * fn - test
 *
 * @a: This is just a non-sense and totally useless dummy function
 *	argument: it has absolutely no effect.
 */
void fn(int a)
{
}

Re: kernel-doc problem

[Randy Dunlap]

On Thu, 19 Aug 2010 15:20:19 +0200 Johannes Berg wrote:

> Randy, all,
> 
> I'm running into a problem where something that I want to be part of a
> description of a struct member or function parameter gets parsed as a
> new section. You can easily see the problem by running below test file
> through kernel-doc, clearly the intent is not to have a new section in
> the middle of function argument descriptions, but I have no idea how I
> could fix this.
> 
> I'd appreciate if you could take a look.
> 
> Thanks,
> Johannes
> 
> --- here's the file ---
> /**
>  * fn - test
>  *
>  * @a: This is just a non-sense and totally useless dummy function
>  *	argument: it has absolutely no effect.
>  */
> void fn(int a)
> {
> }

Colons (':') are bad.  They cause a section instance.
I don't know how to fix it (inside kernel-doc or docproc or xmlto or wherever).
Sometimes I change colon to "--" or "." or something that makes some sense,
but colon is still the better choice if it would work.

The word "example" has a similar problem.  It causes an <informalexample>
markup to begin, but it's not always terminated properly.
See recent commit 3d2be54bab7efd97b642838b9c883869ca5b98be.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: kernel-doc problem

[Johannes Berg]

On Thu, 2010-08-19 at 08:30 -0700, Randy Dunlap wrote:

> > --- here's the file ---
> > /**
> >  * fn - test
> >  *
> >  * @a: This is just a non-sense and totally useless dummy function
> >  *	argument: it has absolutely no effect.
> >  */
> > void fn(int a)
> > {
> > }
> 
> Colons (':') are bad.  They cause a section instance.

Yeah, that's what I found.

> I don't know how to fix it (inside kernel-doc or docproc or xmlto or wherever).
> Sometimes I change colon to "--" or "." or something that makes some sense,
> but colon is still the better choice if it would work.

Ok.

Actually, I can think of something. When we have a line that starts with
this kind of pattern, assume that the next line is a continuation of it
and do not pattern match it, unless there was a blank line. I guess that
needs a special case for @...: though.

johannes