Skip to contentSkip to conversation

kernel-doc problem

DISCUSSION Johannes Berg 2 participants 3 messages Aug 19, 2010

lore
Share & tools
lore
#0 lore raw

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)
{
}

#1 lore raw
Quoted 14 lines · 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

Quoted 10 lines

--- 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 ***

#2 lore raw
Quoted 11 lines · Randy Dunlap
Quoted 10 lines

--- 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)
{
}

Quoted 1 line

Colons (':') are bad. They cause a section instance.

Yeah, that's what I found.

Quoted 3 lines

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