2 # Copyright 1999, 2000, 2001 Patrik Stridvall
4 # This library is free software; you can redistribute it and/or
5 # modify it under the terms of the GNU Lesser General Public
6 # License as published by the Free Software Foundation; either
7 # version 2.1 of the License, or (at your option) any later version.
9 # This library is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 # Lesser General Public License for more details.
14 # You should have received a copy of the GNU Lesser General Public
15 # License along with this library; if not, write to the Free Software
16 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 package winapi_documentation;
23 use config qw($current_dir $wine_dir);
24 use modules qw($modules);
25 use nativeapi qw($nativeapi);
26 use options qw($options);
27 use output qw($output);
28 use winapi qw($win16api $win32api @winapis);
34 sub check_documentation {
39 my $file = $function->file;
40 my $external_name16 = $function->external_name16;
41 my $external_name32 = $function->external_name32;
42 my $internal_name = $function->internal_name;
43 my $module16 = $function->module16;
44 my $module32 = $function->module32;
45 my $ordinal16 = $function->ordinal16;
46 my $ordinal32 = $function->ordinal32;
47 my $documentation = $function->documentation;
48 my $documentation_line = $function->documentation_line;
50 my $documentation_error = 0;
51 my $documentation_warning = 0;
52 if($options->documentation_name ||
53 $options->documentation_ordinal ||
54 $options->documentation_pedantic)
56 my @winapis = ($win16api, $win32api);
57 my @modules = ($module16, $module32);
58 my @external_names = ($external_name16, $external_name32);
59 my @ordinals = ($ordinal16, $ordinal32);
61 defined(my $winapi = shift @winapis) &&
62 defined(my $external_name = shift @external_names) &&
63 defined(my $module = shift @modules) &&
64 defined(my $ordinal = shift @ordinals))
66 if($winapi->is_function_stub_in_module($module, $internal_name)) { next; }
68 my @external_name = split(/\s*\&\s*/, $external_name);
69 my @modules = split(/\s*\&\s*/, $module);
70 my @ordinals = split(/\s*\&\s*/, $ordinal);
72 my $pedantic_failed = 0;
73 while(defined(my $external_name = shift @external_name) &&
74 defined(my $module = shift @modules) &&
75 defined(my $ordinal = shift @ordinals))
78 my $found_ordinal = 0;
80 $module =~ s/\.(acm|dll|drv|exe|ocx)$//; # FIXME: Kludge
81 $module = "kernel" if $module eq "krnl386"; # FIXME: Kludge
83 foreach (split(/\n/, $documentation)) {
84 if(/^(\s*)\*(\s*)(\@|\S+)(\s*)([\(\[])(\w+)\.(\@|\d+)([\)\]])/) {
85 my $external_name2 = $3;
89 if ($winapi->function_wine_extension(lc($module2), $external_name2)) {
90 $output->write("documentation: $external_name2 (\U$module2\E.$ordinal2) is a Wine extension \\\n$documentation\n");
93 if(length($1) != 1 || length($2) < 1 ||
94 length($4) < 1 || $5 ne "(" || $8 ne ")")
99 if($external_name eq $external_name2) {
101 if("\U$module\E" eq $module2 &&
102 $ordinal eq $ordinal2)
109 if((($options->documentation_name && !$found_name) ||
110 ($options->documentation_ordinal && !$found_ordinal)) &&
111 !$winapi->function_wine_extension($module, $external_name))
113 $documentation_error = 1;
114 $output->write("documentation: expected $external_name (\U$module\E.$ordinal): \\\n$documentation\n");
118 if($options->documentation_pedantic && $pedantic_failed) {
119 $documentation_warning = 1;
120 $output->write("documentation: pedantic failed: \\\n$documentation\n");
125 if(!$documentation_error && $options->documentation_wrong) {
126 foreach (split(/\n/, $documentation)) {
127 if(/^\s*\*\s*(\S+)\s*[\(\[]\s*(\w+)\s*\.\s*([^\s\)\]]*)\s*[\)\]].*?$/) {
128 my $external_name = $1;
132 if(!$options->documentation_pedantic && $ordinal ne "@") {
133 $ordinal = int($ordinal);
137 foreach my $entry2 (winapi::get_all_module_internal_ordinal($internal_name)) {
138 (my $external_name2, my $module2, my $ordinal2) = @$entry2;
140 my $_module2 = $module2;
141 $_module2 =~ s/\.(acm|dll|drv|exe|ocx)$//; # FIXME: Kludge
142 $_module2 = "kernel" if $_module2 eq "krnl386"; # FIXME: Kludge
144 if($external_name eq $external_name2 &&
145 lc($module) eq $_module2 &&
146 $ordinal eq $ordinal2 &&
147 ($external_name2 eq "@" ||
148 ($win16api->is_module($module2) && !$win16api->is_function_stub_in_module($module2, $external_name2)) ||
149 ($win32api->is_module($module2) && !$win32api->is_function_stub_in_module($module2, $external_name2))) ||
150 $modules->is_allowed_module_in_file($module2, "$current_dir/$file"))
159 $output->write("documentation: $external_name (\U$module\E.$ordinal) wrong\n");
165 if($options->documentation_comment_indent) {
166 foreach (split(/\n/, $documentation)) {
167 if(/^\s*\*(\s*)\S+(\s*)[\(\[]\s*\w+\s*\.\s*[^\s\)\]]*\s*[\)\]].*?$/) {
172 $indent = length($indent);
174 $spacing =~ s/\t/ /g;
175 $spacing = length($spacing);
177 $comment_indent{$indent}++;
179 $output->write("documentation: comment indent is $indent\n");
181 $comment_spacing{$spacing}++;
186 if($options->documentation_comment_width) {
187 if($documentation =~ /(^\/\*\*+)/) {
188 my $width = length($1);
190 $comment_width{$width}++;
191 if($width <= 65 || $width >= 81) {
192 $output->write("comment is $width columns wide\n");
197 if($options->documentation_arguments) {
198 my $refargument_documentations = $function->argument_documentations;
200 if(defined($refargument_documentations)) {
202 for my $argument_documentation (@$refargument_documentations) {
204 if($argument_documentation ne "") {
205 if($argument_documentation !~ /^\/\*\s+\[(?:in|out|in\/out|\?\?\?)\].*?\*\/$/s) {
206 $output->write("argument $n documentation: \\\n$argument_documentation\n");
214 sub report_documentation {
215 if($options->documentation_comment_indent) {
216 foreach my $indent (sort(keys(%comment_indent))) {
217 my $count = $comment_indent{$indent};
218 $output->write("*.c: $count functions have comment that is indented $indent\n");
222 if($options->documentation_comment_width) {
223 foreach my $width (sort(keys(%comment_width))) {
224 my $count = $comment_width{$width};
225 $output->write("*.c: $count functions have comments of width $width\n");