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.
Unified · Split
| @@ -137,6 +137,8 @@ use strict; · 136 unmodified lines | ||
| 137 | 137 | # should document the "Context:" of the function, e.g. whether the functions |
| 138 | 138 | # can be called form interrupts. Unlike other sections you can end it with an |
| 139 | 139 | # empty line. |
| 140 | +# A non-void function should have a "Return:" section describing the return | |
| 141 | +# value(s). | |
| 140 | 142 | # Example-sections should contain the string EXAMPLE so that they are marked |
| 141 | 143 | # appropriately in DocBook. |
| 142 | 144 | # |
| @@ -315,6 +317,7 @@ my $section_default = "Description"; # default section · 172 unmodified lines | ||
| 315 | 317 | my $section_intro = "Introduction"; |
| 316 | 318 | my $section = $section_default; |
| 317 | 319 | my $section_context = "Context"; |
| 320 | +my $section_return = "Return"; | |
| 318 | 321 | |
| 319 | 322 | my $undescribed = "-- undescribed --"; |
| 320 | 323 | |
| @@ -2038,6 +2041,28 @@ sub check_sections($$$$$$) { · 1717 unmodified lines | ||
| 2038 | 2041 | } |
| 2039 | 2042 | } |
| 2040 | 2043 | |
| 2044 | +## | |
| 2045 | +# Checks the section describing the return value of a function. | |
| 2046 | +sub check_return_section { | |
| 2047 | + my $file = shift; | |
| 2048 | + my $declaration_name = shift; | |
| 2049 | + my $return_type = shift; | |
| 2050 | + | |
| 2051 | + # Ignore an empty return type (It's a macro) | |
| 2052 | + # Ignore functions with a "void" return type. (But don't ignore "void *") | |
| 2053 | + if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { | |
| 2054 | + return; | |
| 2055 | + } | |
| 2056 | + | |
| 2057 | + if (!defined($sections{$section_return}) || | |
| 2058 | + $sections{$section_return} eq "") { | |
| 2059 | + print STDERR "Warning(${file}:$.): " . | |
| 2060 | + "No description found for return value of " . | |
| 2061 | + "'$declaration_name'\n"; | |
| 2062 | + ++$warnings; | |
| 2063 | + } | |
| 2064 | +} | |
| 2065 | + | |
| 2041 | 2066 | ## |
| 2042 | 2067 | # takes a function prototype and the name of the current file being |
| 2043 | 2068 | # processed and spits out all the details stored in the global |
| @@ -2109,6 +2134,15 @@ sub dump_function($$) { · 65 unmodified lines | ||
| 2109 | 2134 | my $prms = join " ", @parameterlist; |
| 2110 | 2135 | check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); |
| 2111 | 2136 | |
| 2137 | + # This check emits a lot of warnings at the moment, because many | |
| 2138 | + # functions don't have a 'Return' doc section. So until the number | |
| 2139 | + # of warnings goes sufficiently down, the check is only performed in | |
| 2140 | + # verbose mode. | |
| 2141 | + # TODO: always perform the check. | |
| 2142 | + if ($verbose) { | |
| 2143 | + check_return_section($file, $declaration_name, $return_type); | |
| 2144 | + } | |
| 2145 | + | |
| 2112 | 2146 | output_declaration($declaration_name, |
| 2113 | 2147 | 'function', |
| 2114 | 2148 | {'function' => $declaration_name, |