kernel-doc (851462444d421c223965b12b836bef63da61b57f) kernel-doc (4092bac77131048b8f69cb1f939326c55d93709f)
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

--- 123 unchanged lines hidden (view full) ---

132# };
133#
134# All descriptions can be multiline, except the short function description.
135#
136# You can also add additional sections. When documenting kernel functions you
137# should document the "Context:" of the function, e.g. whether the functions
138# can be called form interrupts. Unlike other sections you can end it with an
139# empty line.
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

--- 123 unchanged lines hidden (view full) ---

132# };
133#
134# All descriptions can be multiline, except the short function description.
135#
136# You can also add additional sections. When documenting kernel functions you
137# should document the "Context:" of the function, e.g. whether the functions
138# can be called form interrupts. Unlike other sections you can end it with an
139# empty line.
140# A non-void function should have a "Return:" section describing the return
141# value(s).
140# Example-sections should contain the string EXAMPLE so that they are marked
141# appropriately in DocBook.
142#
143# Example:
144# /**
145# * user_function - function that can only be called in user context
146# * @a: some argument
147# * Context: !in_interrupt()

--- 162 unchanged lines hidden (view full) ---

310my $sectcheck;
311my $struct_actual;
312
313my $contents = "";
314my $section_default = "Description"; # default section
315my $section_intro = "Introduction";
316my $section = $section_default;
317my $section_context = "Context";
142# Example-sections should contain the string EXAMPLE so that they are marked
143# appropriately in DocBook.
144#
145# Example:
146# /**
147# * user_function - function that can only be called in user context
148# * @a: some argument
149# * Context: !in_interrupt()

--- 162 unchanged lines hidden (view full) ---

312my $sectcheck;
313my $struct_actual;
314
315my $contents = "";
316my $section_default = "Description"; # default section
317my $section_intro = "Introduction";
318my $section = $section_default;
319my $section_context = "Context";
320my $section_return = "Return";
318
319my $undescribed = "-- undescribed --";
320
321reset_state();
322
323while ($ARGV[0] =~ m/^-(.*)/) {
324 my $cmd = shift @ARGV;
325 if ($cmd eq "-html") {

--- 1708 unchanged lines hidden (view full) ---

2034 ++$warnings;
2035 }
2036 }
2037 }
2038 }
2039}
2040
2041##
321
322my $undescribed = "-- undescribed --";
323
324reset_state();
325
326while ($ARGV[0] =~ m/^-(.*)/) {
327 my $cmd = shift @ARGV;
328 if ($cmd eq "-html") {

--- 1708 unchanged lines hidden (view full) ---

2037 ++$warnings;
2038 }
2039 }
2040 }
2041 }
2042}
2043
2044##
2045# Checks the section describing the return value of a function.
2046sub 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
2066##
2042# takes a function prototype and the name of the current file being
2043# processed and spits out all the details stored in the global
2044# arrays/hashes.
2045sub dump_function($$) {
2046 my $prototype = shift;
2047 my $file = shift;
2048
2049 $prototype =~ s/^static +//;

--- 54 unchanged lines hidden (view full) ---

2104 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
2105 ++$errors;
2106 return;
2107 }
2108
2109 my $prms = join " ", @parameterlist;
2110 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2111
2067# takes a function prototype and the name of the current file being
2068# processed and spits out all the details stored in the global
2069# arrays/hashes.
2070sub dump_function($$) {
2071 my $prototype = shift;
2072 my $file = shift;
2073
2074 $prototype =~ s/^static +//;

--- 54 unchanged lines hidden (view full) ---

2129 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
2130 ++$errors;
2131 return;
2132 }
2133
2134 my $prms = join " ", @parameterlist;
2135 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
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 output_declaration($declaration_name,
2113 'function',
2114 {'function' => $declaration_name,
2115 'module' => $modulename,
2116 'functiontype' => $return_type,
2117 'parameterlist' => \@parameterlist,
2118 'parameterdescs' => \%parameterdescs,
2119 'parametertypes' => \%parametertypes,

--- 452 unchanged lines hidden --- 		2146 output_declaration($declaration_name,
2147 'function',
2148 {'function' => $declaration_name,
2149 'module' => $modulename,
2150 'functiontype' => $return_type,
2151 'parameterlist' => \@parameterlist,
2152 'parameterdescs' => \%parameterdescs,
2153 'parametertypes' => \%parametertypes,

--- 452 unchanged lines hidden ---