include: Add binres.idl.
[wine] / tools / winapi / winapi_documentation.pm
1 #
2 # Copyright 1999, 2000, 2001 Patrik Stridvall
3 #
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.
8 #
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.
13 #
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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
17 #
18
19 package winapi_documentation;
20
21 use strict;
22
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);
29
30 my %comment_width;
31 my %comment_indent;
32 my %comment_spacing;
33
34 sub check_documentation($) {
35     local $_;
36
37     my $function = shift;
38
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;
49
50     my $documentation_error = 0;
51     my $documentation_warning = 0;
52     if($options->documentation_name ||
53        $options->documentation_ordinal ||
54        $options->documentation_pedantic)
55     {
56         my @winapis = ($win16api, $win32api);
57         my @modules = ($module16, $module32);
58         my @external_names = ($external_name16, $external_name32);
59         my @ordinals = ($ordinal16, $ordinal32);
60         while(
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))
65         {
66             if($winapi->is_function_stub_in_module($module, $internal_name)) { next; }
67
68             my @external_name = split(/\s*\&\s*/, $external_name);
69             my @modules = split(/\s*\&\s*/, $module);
70             my @ordinals = split(/\s*\&\s*/, $ordinal);
71
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))
76             {
77                 my $found_name = 0;
78                 my $found_ordinal = 0;
79
80                 $module =~ s/\.(acm|dll|drv|exe|ocx)$//; # FIXME: Kludge
81                 $module = "kernel" if $module eq "krnl386"; # FIXME: Kludge
82
83                 foreach (split(/\n/, $documentation)) {
84                     if(/^(\s*)\*(\s*)(\@|\S+)(\s*)([\(\[])(\w+)\.(\@|\d+)([\)\]])/) {
85                         my $external_name2 = $3;
86                         my $module2 = $6;
87                         my $ordinal2 = $7;
88
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");
91                         }
92
93                         if(length($1) != 1 || length($2) < 1 ||
94                            length($4) < 1 || $5 ne "(" || $8 ne ")")
95                         {
96                             $pedantic_failed = 1;
97                         }
98
99                         if($external_name eq $external_name2) {
100                             $found_name = 1;
101                             if("\U$module\E" eq $module2 &&
102                                $ordinal eq $ordinal2)
103                             {
104                                 $found_ordinal = 1;
105                             }
106                         }
107                     }
108                 }
109                 if((($options->documentation_name && !$found_name) ||
110                    ($options->documentation_ordinal && !$found_ordinal)) &&
111                    !$winapi->is_function_stub($module, $external_name) &&
112                    !$winapi->function_wine_extension($module, $external_name))
113                 {
114                     $documentation_error = 1;
115                     $output->write("documentation: expected $external_name (\U$module\E.$ordinal): \\\n$documentation\n");
116                 }
117
118             }
119             if($options->documentation_pedantic && $pedantic_failed) {
120                 $documentation_warning = 1;
121                 $output->write("documentation: pedantic failed: \\\n$documentation\n");
122             }
123         }
124     }
125
126     if(!$documentation_error && $options->documentation_wrong) {
127         foreach (split(/\n/, $documentation)) {
128             if (/^\s*\*\s*(\S+)\s*[\(\[]\s*(\w+(?:\.(?:DRV|EXE|OCX|VXD))?)\s*\.\s*([^\s\)\]]*)\s*[\)\]].*?$/) {
129                 my $external_name = $1;
130                 my $module = $2;
131                 my $ordinal = $3;
132
133                 if ($ordinal eq "@") {
134                     # Nothing
135                 } elsif ($ordinal =~ /^\d+$/) {
136                     $ordinal = int($ordinal);
137                 } elsif ($ordinal eq "init") {
138                     $ordinal = 0;
139                 } else {
140                     $output->write("documentation: invalid ordinal for $external_name (\U$module\E.$ordinal)\n");
141                     next;
142                 }
143
144                 my $found = 0;
145                 foreach my $entry2 (winapi::get_all_module_internal_ordinal($internal_name)) {
146                     (my $external_name2, my $module2, my $ordinal2) = @$entry2;
147
148                     my $_module2 = $module2;
149                     $_module2 =~ s/\.(acm|dll|drv|exe|ocx)$//; # FIXME: Kludge
150                     $_module2 = "kernel" if $_module2 eq "krnl386"; # FIXME: Kludge
151
152                     if($external_name eq $external_name2 &&
153                        lc($module) eq $_module2 &&
154                        $ordinal eq $ordinal2 &&
155                        ($external_name2 eq "@" ||
156                         ($win16api->is_module($module2) && !$win16api->is_function_stub_in_module($module2, $external_name2)) ||
157                         ($win32api->is_module($module2) && !$win32api->is_function_stub_in_module($module2, $external_name2))) ||
158                         $modules->is_allowed_module_in_file($module2, "$current_dir/$file"))
159                     {
160                         $found = 1;
161                         last;
162                     }
163
164
165                 }
166
167                 if (!$found && $external_name ne "DllMain" && $ordinal ne "0") {
168                     $output->write("documentation: $external_name (\U$module\E.$ordinal) not declared in the spec file\n");
169                 }
170             }
171         }
172     }
173
174     if($options->documentation_comment_indent) {
175         foreach (split(/\n/, $documentation)) {
176             if(/^\s*\*(\s*)\S+(\s*)[\(\[]\s*\w+\s*\.\s*[^\s\)\]]*\s*[\)\]].*?$/) {
177                 my $indent = $1;
178                 my $spacing = $2;
179
180                 $indent =~ s/\t/        /g;
181                 $indent = length($indent);
182
183                 $spacing =~ s/\t/        /g;
184                 $spacing = length($spacing);
185
186                 $comment_indent{$indent}++;
187                 if($indent >= 20) {
188                     $output->write("documentation: comment indent is $indent\n");
189                 }
190                 $comment_spacing{$spacing}++;
191             }
192         }
193     }
194
195     if($options->documentation_comment_width) {
196         if($documentation =~ /(^\/\*\*+)/) {
197             my $width = length($1);
198
199             $comment_width{$width}++;
200             if($width <= 65 || $width >= 81) {
201                 $output->write("comment is $width columns wide\n");
202             }
203         }
204     }
205
206     if($options->documentation_arguments) {
207         my $refargument_documentations = $function->argument_documentations;
208
209         if(defined($refargument_documentations)) {
210             my $n = 0;
211             for my $argument_documentation (@$refargument_documentations) {
212                 $n++;
213                 if($argument_documentation ne "") {
214                     if($argument_documentation !~ /^\/\*\s+\[(?:in|out|in\/out|\?\?\?|I|O|I\/O)\].*?\*\/$/s) {
215                         $output->write("argument $n documentation: \\\n$argument_documentation\n");
216                     }
217                 }
218             }
219         }
220     }
221 }
222
223 sub report_documentation() {
224     if($options->documentation_comment_indent) {
225         foreach my $indent (sort(keys(%comment_indent))) {
226             my $count = $comment_indent{$indent};
227             $output->write("*.c: $count functions have comment that is indented $indent\n");
228         }
229     }
230
231     if($options->documentation_comment_width) {
232         foreach my $width (sort(keys(%comment_width))) {
233             my $count = $comment_width{$width};
234             $output->write("*.c: $count functions have comments of width $width\n");
235         }
236     }
237 }
238
239 1;