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

List:       linux-doc
Subject:    Re: scripts/kernel-doc: no warning or error on lots of missing function parameters
From:       Randy Dunlap <rdunlap () infradead ! org>
Date:       2017-12-31 0:54:30
Message-ID: e53b8a89-5478-5d26-928d-3b6bc44fe2ba () infradead ! org
[Download RAW message or body]

On 12/30/2017 04:32 PM, Mauro Carvalho Chehab wrote:
> Em Sat, 30 Dec 2017 10:38:03 -0800
> Randy Dunlap <rdunlap@infradead.org> escreveu:
> 
> > > > > > Using linux-next-20171222, with its ("new") scripts/kernel-doc, I see
> > > > > > 
> > > > > > > grep -c  not.described doc005.out    
> > > > > > 86
> > > > > > 
> > > > > > but if I use scripts/kernel-doc from linux-4.15-rc5 (in \
> > > > > > linux-next-20171222), I see 
> > > > > > > grep -c No.description.found doc006.out    
> > > > > > 305
> 
> > > $ git checkout next-20171221  
> > 
> > Please try it with linux-next-20171222 instead of 1221.
> > It has many more patches to scripts/kernel-doc.
> 
> OK, now I was able to reproduce the issue. The problem is that the
> logic with inhibits warning outputs is incomplete: it doesn't take
> into account "-export" and "-internal" command line arguments.
> Sorry for the mess.
> 
> Please check if the enclosed patches fix the issue.
> 
> Regards,
> Mauro
> 

Yes, this seems to be working (I am just doing a quick look for now).

Acked-and-Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> 
> [PATCH] scripts: kernel_doc: better handle show warnings logic
> 
> The logic with inhibits warnings for definitions that is not
> output is incomplete: it doesn't cover the cases where
> OUTPUT_INTERNAL and OUTPUT_EXPORTED are used.
> 
> As the most common case is OUTPUT_ALL, place it first,
> in order to optimize a litte bit the check logic.
> 
> Fixes: 2defb2729217 ("scripts: kernel-doc: apply filtering rules to warnings")
> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 1e2b35ce1c9d..fee8952037b1 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1140,6 +1140,44 @@ sub dump_struct($$) {
> }
> }
> 
> +
> +sub show_warnings($$) {
> +	my $functype = shift;
> +	my $name = shift;
> +
> +	return 1 if ($output_selection == OUTPUT_ALL);
> +
> +	if ($output_selection == OUTPUT_EXPORTED) {
> +		if (defined($function_table{$name})) {
> +			return 1;
> +		} else {
> +			return 0;
> +		}
> +	}
> +        if ($output_selection == OUTPUT_INTERNAL) {
> +		if (!($functype eq "function" && defined($function_table{$name}))) {
> +			return 1;
> +		} else {
> +			return 0;
> +		}
> +	}
> +	if ($output_selection == OUTPUT_INCLUDE) {
> +		if (defined($function_table{$name})) {
> +			return 1;
> +		} else {
> +			return 0;
> +		}
> +	}
> +	if ($output_selection == OUTPUT_EXCLUDE) {
> +		if (!defined($function_table{$name})) {
> +			return 1;
> +		} else {
> +			return 0;
> +		}
> +	}
> +	die("Please add the new output type at show_warnings()");
> +}
> +
> sub dump_enum($$) {
> my $x = shift;
> my $file = shift;
> @@ -1160,11 +1198,7 @@ sub dump_enum($$) {
> 	    push @parameterlist, $arg;
> 	    if (!$parameterdescs{$arg}) {
> 		$parameterdescs{$arg} = $undescribed;
> -	        if (($output_selection == OUTPUT_ALL) ||
> -		    ($output_selection == OUTPUT_INCLUDE &&
> -		     defined($function_table{$declaration_name})) ||
> -		    ($output_selection == OUTPUT_EXCLUDE &&
> -		     !defined($function_table{$declaration_name}))) {
> +	        if (show_warnings("enum", $declaration_name)) {
> 			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum \
> '$declaration_name'\n";  }
> 	    }
> @@ -1173,11 +1207,7 @@ sub dump_enum($$) {
> 
> 	while (my ($k, $v) = each %parameterdescs) {
> 	    if (!exists($_members{$k})) {
> -	        if (($output_selection == OUTPUT_ALL) ||
> -		    ($output_selection == OUTPUT_INCLUDE &&
> -		     defined($function_table{$declaration_name})) ||
> -		    ($output_selection == OUTPUT_EXCLUDE &&
> -		     !defined($function_table{$declaration_name}))) {
> +	        if (show_warnings("enum", $declaration_name)) {
> 		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in \
> '$declaration_name'\n";  }
> 	    }
> @@ -1385,11 +1415,7 @@ sub push_parameter($$$$) {
> 	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
> 		$parameterdescs{$param} = $undescribed;
> 
> -	        if (($output_selection == OUTPUT_ALL) ||
> -		    ($output_selection == OUTPUT_INCLUDE &&
> -		     defined($function_table{$declaration_name})) ||
> -		    ($output_selection == OUTPUT_EXCLUDE &&
> -		     !defined($function_table{$declaration_name}))) {
> +	        if (show_warnings($type, $declaration_name)) {
> 			print STDERR
> 			      "${file}:$.: warning: Function parameter or member '$param' not described \
> in '$declaration_name'\n";  ++$warnings;
> 
> 


-- 
~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]