[prev in list] [next in list] [prev in thread] [next in thread] 

List:       linux-doc
Subject:    Re: [RFC][PATCH] Kernel-doc script fixes
From:       Randy Dunlap <randy.dunlap () oracle ! com>
Date:       2010-01-12 21:27:52
Message-ID: 20100112132752.f59f375b.randy.dunlap () oracle ! com
[Download RAW message or body]

On Tue, 12 Jan 2010 13:49:16 +0200 Ilya Dryomov wrote:

> Hello,
> 
> When I try to check multiple files with kernel-doc script I always get wrong
> line numbers in the output of the script (by 'check' I mean discard the
> generated documentation and see if there are any errors/warnings). For example
> if you do
> 
> 	scripts/kernel-doc > /dev/null mm/*.c
> 
> you will get the following:
> 
> 	Warning(mm/debug-pagealloc.c): no structured comments found
> 	Warning(mm/failslab.c): no structured comments found
> 	Warning(mm/hwpoison-inject.c): no structured comments found
> 
> 	.......... (taken out)
> 
> 	Warning(mm/pagewalk.c:40254): Excess function parameter 'mm' description
> 		in 'walk_page_range'
> 	Warning(mm/percpu.c:42563): Excess function parameter 'flush'
> 		description in 'pcpu_depopulate_chunk'
> 
> 	.......... (taken out)
> 
> 	Warning(mm/util.c): no structured comments found
> 	Error(mm/vmscan.c:68954): cannot understand prototype:
> 		'SCAN_UNEVICTABLE_BATCH_SIZE 16UL  '
> 
> So it says that vmscan.c has an error on line 68954, but there are only 2892
> lines in that file! Although my Perl skills are rather bad, I looked at the
> script and found out that it uses internal Perl variable $. for reporting line
> numbers. With the current implementation it's OK to do that if you pass it
> only one file, but the usage() says
> 
> 	c source file(s) > outputfile\n";
> 
> so it should be perfectly good to pass it multiple files. Now the problem is
> that $. keeps track of the current record number (which is line number by
> default). But if you pass it multiple files, it does not wrap at the end of
> file, and therefore contains the *total* number of processed lines. I also
> found the -filelist option, but apparently the implementation is broken, and
> it was broken from the very first git commit.
> 
> I suppose we can fix line numbering by introducing a simple assignment $. = 1
> before processing every new file. As for the -filelist option I suggest the
> removal (I wasn't able to find any users of it, moreover it's not even listed in
> the usage() output, so presumably nobody knows about it).


OK, I applied both patches.  They will be in linux-next for a few weeks,
then be merged into mainline.

In the future, please put the patch description (like most of above)
into each patch email body, not as a separate email.  I had to cut&paste
both patches to make them appropriate.

You can see them here if you need to understand "appropriate":
http://oss.oracle.com/~rdunlap/kernel-doc-patches/current/

Thanks.
---
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
[prev in list] [next in list] [prev in thread] [next in thread]