diff options
author | Yacine Belkadi <yacine.belkadi.1@gmail.com> | 2012-11-27 21:27:19 +0100 |
---|---|---|
committer | Michal Marek <mmarek@suse.cz> | 2012-12-06 11:49:28 +0100 |
commit | 9a52aeeb92853167a67225602b9783f3cf4e578e (patch) | |
tree | aa7da70e2e13d085b2c0b7999eef8aff2aa89ab7 | |
parent | ddf5eabd20c6cc2814fa2c00a1a033776fbc3e44 (diff) | |
download | linux-stable-9a52aeeb92853167a67225602b9783f3cf4e578e.tar.gz linux-stable-9a52aeeb92853167a67225602b9783f3cf4e578e.tar.bz2 linux-stable-9a52aeeb92853167a67225602b9783f3cf4e578e.zip |
scripts/kernel-doc: check that non-void fcts describe their return value
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Michal Marek <mmarek@suse.cz>
-rwxr-xr-x | scripts/kernel-doc | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 46e7aff80d1a..28b761567815 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -137,6 +137,8 @@ use strict; # should document the "Context:" of the function, e.g. whether the functions # can be called form interrupts. Unlike other sections you can end it with an # empty line. +# A non-void function should have a "Return:" section describing the return +# value(s). # Example-sections should contain the string EXAMPLE so that they are marked # appropriately in DocBook. # @@ -315,6 +317,7 @@ my $section_default = "Description"; # default section my $section_intro = "Introduction"; my $section = $section_default; my $section_context = "Context"; +my $section_return = "Return"; my $undescribed = "-- undescribed --"; @@ -2039,6 +2042,28 @@ sub check_sections($$$$$$) { } ## +# Checks the section describing the return value of a function. +sub check_return_section { + my $file = shift; + my $declaration_name = shift; + my $return_type = shift; + + # Ignore an empty return type (It's a macro) + # Ignore functions with a "void" return type. (But don't ignore "void *") + if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { + return; + } + + if (!defined($sections{$section_return}) || + $sections{$section_return} eq "") { + print STDERR "Warning(${file}:$.): " . + "No description found for return value of " . + "'$declaration_name'\n"; + ++$warnings; + } +} + +## # takes a function prototype and the name of the current file being # processed and spits out all the details stored in the global # arrays/hashes. @@ -2109,6 +2134,15 @@ sub dump_function($$) { my $prms = join " ", @parameterlist; check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); + # This check emits a lot of warnings at the moment, because many + # functions don't have a 'Return' doc section. So until the number + # of warnings goes sufficiently down, the check is only performed in + # verbose mode. + # TODO: always perform the check. + if ($verbose) { + check_return_section($file, $declaration_name, $return_type); + } + output_declaration($declaration_name, 'function', {'function' => $declaration_name, |