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