tools/winapi_check/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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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+)\s*\.\s*([^\s\)\]]*)\s*[\)\]].*?$/) {
 129                 my $external_name = $1;
 130                 my $module = $2;
 131                 my $ordinal = $3;
 132
 133                 if(!$options->documentation_pedantic && $ordinal ne "@") {
 134                     $ordinal = int($ordinal);
 135                 }
 136
 137                 my $found = 0;
 138                 foreach my $entry2 (winapi::get_all_module_internal_ordinal($internal_name)) {
 139                     (my $external_name2, my $module2, my $ordinal2) = @$entry2;
 140
 141                     my $_module2 = $module2;
 142                     $_module2 =~ s/\.(acm|dll|drv|exe|ocx)$//; # FIXME: Kludge
 143                     $_module2 = "kernel" if $_module2 eq "krnl386"; # FIXME: Kludge
 144
 145                     if($external_name eq $external_name2 &&
 146                        lc($module) eq $_module2 &&
 147                        $ordinal eq $ordinal2 &&
 148                        ($external_name2 eq "@" ||
 149                         ($win16api->is_module($module2) && !$win16api->is_function_stub_in_module($module2, $external_name2)) ||
 150                         ($win32api->is_module($module2) && !$win32api->is_function_stub_in_module($module2, $external_name2))) ||
 151                         $modules->is_allowed_module_in_file($module2, "$current_dir/$file"))
 152                     {
 153                         $found = 1;
 154                         last;
 155                     }
 156
 157
 158                 }
 159                 if(!$found) {
 160                     $output->write("documentation: $external_name (\U$module\E.$ordinal) wrong\n");
 161                 }
 162             }
 163         }
 164     }
 165
 166     if($options->documentation_comment_indent) {
 167         foreach (split(/\n/, $documentation)) {
 168             if(/^\s*\*(\s*)\S+(\s*)[\(\[]\s*\w+\s*\.\s*[^\s\)\]]*\s*[\)\]].*?$/) {
 169                 my $indent = $1;
 170                 my $spacing = $2;
 171
 172                 $indent =~ s/\t/        /g;
 173                 $indent = length($indent);
 174
 175                 $spacing =~ s/\t/        /g;
 176                 $spacing = length($spacing);
 177
 178                 $comment_indent{$indent}++;
 179                 if($indent >= 20) {
 180                     $output->write("documentation: comment indent is $indent\n");
 181                 }
 182                 $comment_spacing{$spacing}++;
 183             }
 184         }
 185     }
 186
 187     if($options->documentation_comment_width) {
 188         if($documentation =~ /(^\/\*\*+)/) {
 189             my $width = length($1);
 190
 191             $comment_width{$width}++;
 192             if($width <= 65 || $width >= 81) {
 193                 $output->write("comment is $width columns wide\n");
 194             }
 195         }
 196     }
 197
 198     if($options->documentation_arguments) {
 199         my $refargument_documentations = $function->argument_documentations;
 200
 201         if(defined($refargument_documentations)) {
 202             my $n = 0;
 203             for my $argument_documentation (@$refargument_documentations) {
 204                 $n++;
 205                 if($argument_documentation ne "") {
 206                     if($argument_documentation !~ /^\/\*\s+\[(?:in|out|in\/out|\?\?\?|I|O|I\/O)\].*?\*\/$/s) {
 207                         $output->write("argument $n documentation: \\\n$argument_documentation\n");
 208                     }
 209                 }
 210             }
 211         }
 212     }
 213 }
 214
 215 sub report_documentation {
 216     if($options->documentation_comment_indent) {
 217         foreach my $indent (sort(keys(%comment_indent))) {
 218             my $count = $comment_indent{$indent};
 219             $output->write("*.c: $count functions have comment that is indented $indent\n");
 220         }
 221     }
 222
 223     if($options->documentation_comment_width) {
 224         foreach my $width (sort(keys(%comment_width))) {
 225             my $count = $comment_width{$width};
 226             $output->write("*.c: $count functions have comments of width $width\n");
 227         }
 228     }
 229 }
 230
 231 1;