git.oblomov.eu Git - wine/blob - tools/winapi_check/winapi_documentation.pm

   1 package winapi_documentation;
   2
   3 use strict;
   4
   5 my %comment_width;
   6 my %comment_indent;
   7 my %comment_spacing;
   8
   9 sub check_documentation {
  10     my $options = shift;
  11     my $output = shift;
  12     my $win16api = shift;
  13     my $win32api = shift;
  14     my $function = shift;
  15
  16     my $module16 = $function->module16;
  17     my $module32 = $function->module32;
  18     my $external_name16 = $function->external_name16;
  19     my $external_name32 = $function->external_name32;
  20     my $internal_name = $function->internal_name;
  21     my $documentation = $function->documentation;
  22     my @argument_documentations = @{$function->argument_documentations};
  23
  24     # FIXME: Not correct
  25     if(defined($external_name16)) {
  26         $external_name16 = (split(/\s*&\s*/, $external_name16))[0];
  27     }
  28
  29     # FIXME: Not correct
  30     if(defined($external_name32)) {
  31         $external_name32 = (split(/\s*&\s*/, $external_name32))[0];
  32     }
  33
  34     my $external_name;
  35     my $name1;
  36     my $name2;
  37
  38     if(defined($module16) && !defined($module32)) {
  39         my @uc_modules16 = split(/\s*\&\s*/, uc($module16));
  40         push @uc_modules16, "WIN16";
  41
  42         $name1 = $internal_name;
  43         foreach my $uc_module16 (@uc_modules16) {
  44             if($name1 =~ s/^$uc_module16\_//) { last; }
  45         }
  46
  47         $name2 = $name1;
  48         $name2 =~ s/(?:_)?16$//;
  49         $name2 =~ s/16_fn/16_/;
  50
  51         $external_name = $external_name16;
  52     } elsif(!defined($module16) && defined($module32)) {
  53         my @uc_modules32 = split(/\s*\&\s*/, uc($module32));
  54         push @uc_modules32, "wine";
  55
  56         foreach my $uc_module32 (@uc_modules32) {
  57             if($uc_module32 =~ /^WS2_32$/) {
  58                 push @uc_modules32, "WSOCK32";
  59             }
  60         }
  61
  62         $name1 = $internal_name;
  63         foreach my $uc_module32 (@uc_modules32) {
  64             if($name1 =~ s/^$uc_module32\_//) { last; }
  65         }
  66
  67         $name2 = $name1;
  68         $name2 =~ s/AW$//;
  69
  70         $external_name = $external_name32;
  71     } else {
  72         my @uc_modules = split(/\s*\&\s*/, uc($module16));
  73         push @uc_modules, split(/\s*\&\s*/, uc($module32));
  74
  75         $name1 = $internal_name;
  76         foreach my $uc_module (@uc_modules) {
  77             if($name1 =~ s/^$uc_module\_//) { last; }
  78         }
  79
  80         $name2 = $name1;
  81         $external_name = $external_name32;
  82     }
  83
  84     if(!defined($external_name)) {
  85         $external_name = $internal_name;
  86     }
  87
  88     if($options->documentation_name) {
  89         my $n = 0;
  90         if((++$n && defined($module16) && defined($external_name16) &&
  91             $external_name16 ne "@" && $documentation !~ /\b\Q$external_name16\E\b/) ||
  92            (++$n && defined($module16) && defined($external_name16) &&
  93             $external_name16 eq "@" && $documentation !~ /\@/) ||
  94            (++$n && defined($module32) && defined($external_name32) &&
  95             $external_name32 ne "@" && $documentation !~ /\b\Q$external_name32\E\b/) ||
  96            (++$n && defined($module32) && defined($external_name32) &&
  97             $external_name32 eq "@" && $documentation !~ /\@/))
  98         {
  99             my $external_name = ($external_name16, $external_name32)[($n-1)/2];
 100             if($options->documentation_pedantic || $documentation !~ /\b(?:$internal_name|$name1|$name2)\b/) {
 101                 $output->write("documentation: wrong or missing name ($external_name) \\\n$documentation\n");
 102             }
 103         }
 104     }
 105
 106     if($options->documentation_ordinal) {
 107         if(defined($module16)) {
 108             my @modules16 = split(/\s*\&\s*/, $module16);
 109             my @ordinals16 = split(/\s*\&\s*/, $win16api->function_internal_ordinal($internal_name));
 110
 111             my $module16;
 112             my $ordinal16;
 113             while(defined($module16 = shift @modules16) && defined($ordinal16 = shift @ordinals16)) {
 114                 if($documentation !~ /\b\U$module16\E\.\Q$ordinal16\E/) {
 115                     $output->write("documentation: wrong or missing ordinal " .
 116                                    "expected (\U$module16\E.$ordinal16) \\\n$documentation\n");
 117                 }
 118             }
 119         }
 120
 121         if(defined($module32)) {
 122             my @modules32 = split(/\s*\&\s*/, $module32);
 123             my @ordinals32 = split(/\s*\&\s*/, $win32api->function_internal_ordinal($internal_name));
 124
 125             my $module32;
 126             my $ordinal32;
 127             while(defined($module32 = shift @modules32) && defined($ordinal32 = shift @ordinals32)) {
 128                 if($documentation !~ /\b\U$module32\E\.\Q$ordinal32\E/) {
 129                     $output->write("documentation: wrong or missing ordinal " .
 130                                    "expected (\U$module32\E.$ordinal32) \\\n$documentation\n");
 131                 }
 132             }
 133         }
 134     }
 135
 136     # FIXME: Not correct
 137     if($options->documentation_pedantic) {
 138         my $ordinal = (split(/\s*\&\s*/, $win16api->function_internal_ordinal($internal_name)))[0];
 139         if(defined($ordinal) && $documentation !~ /^ \*\s+(?:\@|\w+)(?:\s+[\(\[]\w+\.(?:\@|\d+)[\)\]])+/m) {
 140             $output->write("documentation: pedantic check failed \\\n$documentation\n");
 141         }
 142     }
 143
 144     if($options->documentation_comment_indent) {
 145         if($documentation =~ /^ \*(\s*)\w+(\s*)([\(\[])\s*\w+\.\s*(?:\@|\d+)\s*([\)\]])/m) {
 146             my $indent = $1;
 147             my $spacing = $2;
 148             my $left = $3;
 149             my $right = $4;
 150
 151             $indent =~ s/\t/        /g;
 152             $indent = length($indent);
 153
 154             $spacing =~ s/\t/        /g;
 155             $spacing = length($spacing);
 156
 157             $comment_indent{$indent}++;
 158             if($indent >= 20) {
 159                 $output->write("documentation: comment indent is $indent\n");
 160             }
 161
 162             $comment_spacing{$spacing}++;
 163         }
 164     }
 165
 166     if($options->documentation_comment_width) {
 167         if($documentation =~ /(^\/\*\*+)/) {
 168             my $width = length($1);
 169
 170             $comment_width{$width}++;
 171             if($width <= 65 || $width >= 81) {
 172                 $output->write("comment is $width columns wide\n");
 173             }
 174         }
 175     }
 176
 177     if($options->documentation_arguments) {
 178         my $n = 0;
 179         for my $argument_documentation (@argument_documentations) {
 180             $n++;
 181             if($argument_documentation ne "") {
 182                 if($argument_documentation !~ /^\/\*\s+\[(?:in|out|in\/out|\?\?\?)\].*?\*\/$/s) {
 183                     $output->write("argument $n documentation: \\\n$argument_documentation\n");
 184                 }
 185             }
 186         }
 187     }
 188 }
 189
 190 sub report_documentation {
 191     my $options = shift;
 192     my $output = shift;
 193
 194     if($options->documentation_comment_indent) {
 195         foreach my $indent (sort(keys(%comment_indent))) {
 196             my $count = $comment_indent{$indent};
 197             $output->write("*.c: $count functions have comment that is indented $indent\n");
 198         }
 199     }
 200
 201     if($options->documentation_comment_width) {
 202         foreach my $width (sort(keys(%comment_width))) {
 203             my $count = $comment_width{$width};
 204             $output->write("*.c: $count functions have comments of width $width\n");
 205         }
 206     }
 207 }
 208
 209 1;