How to fix DocBook parsers for private fields inside #ifdefs

Em Mon, 5 Oct 2015 04:56:35 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 1 Oct 2015 14:21:07 -0300
> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> 
> > They're all after a private comment:
> > 	/* Private: internal use only */
> > 
> > So, according with Documentation/kernel-doc-nano-HOWTO.txt, they shold
> > have been ignored.
> > 
> > Still, the scripts produce warnings for them:
> 
> Sorry, I've been away from the keyboard for a few days and am only now
> catching up.
> 
> The problem is that kernel-doc is dumb...the test is case-sensitive, so
> it needs to be "private:", not "Private:".  I'm sure there's a magic perl
> regex parameter to make the test case-insensitive; when I get a chance
> I'll figure it out and put it in there.

Ah, that makes sense. Adding an "i" to the end of the regex expression
should make it case-insensitive:

-       $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-       $members =~ s/\/\*\s*private:.*//gos;
+       $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+       $members =~ s/\/\*\s*private:.*//gosi;

Patch enclosed. Yet, I guess nobody would try to use PRIVATE: So, 
another alternative would be to do, instead:

-	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-	$members =~ s/\/\*\s*private:.*//gos;
+	$members =~ s/\/\*\s*[Pp]rivate:.*?\/\*\s*public:.*?\*\///gos;
+	$members =~ s/\/\*\s*[Pp]rivate:.*//gos;

Whatever works best for you.

> (Of course, once you fix that glitch, you'll get gripes about the fields
> that are marked private but documented anyway.  Like I said, kernel-doc
> is dumb.)

Yeah, now I'm getting those warnings:

.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'state' description in 'vb2_buffer'
.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'queued_entry' description in 'vb2_buffer'
.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'done_entry' description in 'vb2_buffer'

I'll fix that.

-

DocBook: Fix kernel-doc to be case-insensitive for private:

On some places, people could use Private: to tag the private fields
of an struct. So, be case-insensitive when parsing "private:"
meta-tag.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

How to fix DocBook parsers for private fields inside #ifdefs

Commit Message

Comments

Patch