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     local $_;
  11
  12     my $options = shift;
  13     my $output = shift;
  14     my $win16api = shift;
  15     my $win32api = shift;
  16     my $function = shift;
  17
  18     my $module16 = $function->module16;
  19     my $module32 = $function->module32;
  20     my $external_name16 = $function->external_name16;
  21     my $external_name32 = $function->external_name32;
  22     my $internal_name = $function->internal_name;
  23     my $documentation = $function->documentation;
  24     my $documentation_line = $function->documentation_line;
  25     my @argument_documentations = @{$function->argument_documentations};
  26
  27     if($options->documentation_name ||
  28        $options->documentation_ordinal ||
  29        $options->documentation_pedantic)
  30     {
  31         my @winapis = ($win16api, $win32api);
  32         my @modules = ($module16, $module32);
  33         my @external_names = ($external_name16, $external_name32);
  34         while(
  35               defined(my $winapi = shift @winapis) &&
  36               defined(my $external_name = shift @external_names) &&
  37               defined(my $module = shift @modules))
  38         {
  39             if($winapi->function_stub($internal_name)) { next; }
  40
  41             my @external_name = split(/\s*\&\s*/, $external_name);
  42             my @modules = split(/\s*\&\s*/, $module);
  43             my @ordinals = split(/\s*\&\s*/, $winapi->function_internal_ordinal($internal_name));
  44
  45             my $pedantic_failed = 0;
  46             while(defined(my $external_name = shift @external_name) &&
  47                   defined(my $module = shift @modules) &&
  48                   defined(my $ordinal = shift @ordinals))
  49             {
  50                 my $found_name = 0;
  51                 my $found_ordinal = 0;
  52                 foreach (split(/\n/, $documentation)) {
  53                     if(/^(\s*)\*(\s*)(\@|\S+)(\s*)([\(\[])(\w+)\.(\@|\d+)([\)\]])/) {
  54                         my $external_name2 = $3;
  55                         my $module2 = $6;
  56                         my $ordinal2 = $7;
  57
  58                         if(length($1) != 1 || length($2) < 1 ||
  59                            length($4) < 1 || $5 ne "(" || $8 ne ")")
  60                         {
  61                             $pedantic_failed = 1;
  62                         }
  63
  64                         if($external_name eq $external_name2) {
  65                             $found_name = 1;
  66                             if("\U$module\E" eq $module2 &&
  67                                $ordinal eq $ordinal2)
  68                             {
  69                                 $found_ordinal = 1;
  70                             }
  71                         }
  72                     }
  73                 }
  74                 if(($options->documentation_name && !$found_name) ||
  75                    ($options->documentation_ordinal && !$found_ordinal))
  76                 {
  77                     $output->write("documentation: expected $external_name (\U$module\E.$ordinal): \\\n$documentation\n");
  78                 }
  79
  80             }
  81             if($options->documentation_pedantic && $pedantic_failed) {
  82                 $output->write("documentation: pedantic failed: \\\n$documentation\n");
  83             }
  84         }
  85     }
  86
  87     if($options->documentation_wrong) {
  88         foreach (split(/\n/, $documentation)) {
  89             if(/^\s*\*\s*(\S+)\s*[\(\[]\s*(\w+)\s*\.\s*([^\s\)\]]*)\s*[\)\]].*?$/) {
  90                 my $external_name = $1;
  91                 my $module = $2;
  92                 my $ordinal = $3;
  93
  94                 my $found = 0;
  95                 foreach my $entry2 (winapi::get_all_module_internal_ordinal($internal_name)) {
  96                     (my $external_name2, my $module2, my $ordinal2) = @$entry2;
  97
  98                     if($external_name eq $external_name2 &&
  99                        lc($module) eq $module2 &&
 100                        $ordinal eq $ordinal2)
 101                     {
 102                         $found = 1;
 103                     }
 104                 }
 105                 if(!$found) {
 106                     $output->write("documentation: $external_name (\U$module\E.$ordinal) wrong\n");
 107                 }
 108             }
 109         }
 110     }
 111
 112     if($options->documentation_comment_indent) {
 113         if($documentation =~ /^ \*(\s*)\w+(\s*)([\(\[])\s*\w+\.\s*(?:\@|\d+)\s*([\)\]])/m) {
 114             my $indent = $1;
 115             my $spacing = $2;
 116             my $left = $3;
 117             my $right = $4;
 118
 119             $indent =~ s/\t/        /g;
 120             $indent = length($indent);
 121
 122             $spacing =~ s/\t/        /g;
 123             $spacing = length($spacing);
 124
 125             $comment_indent{$indent}++;
 126             if($indent >= 20) {
 127                 $output->write("documentation: comment indent is $indent\n");
 128             }
 129
 130             $comment_spacing{$spacing}++;
 131         }
 132     }
 133
 134     if($options->documentation_comment_width) {
 135         if($documentation =~ /(^\/\*\*+)/) {
 136             my $width = length($1);
 137
 138             $comment_width{$width}++;
 139             if($width <= 65 || $width >= 81) {
 140                 $output->write("comment is $width columns wide\n");
 141             }
 142         }
 143     }
 144
 145     if($options->documentation_arguments) {
 146         my $n = 0;
 147         for my $argument_documentation (@argument_documentations) {
 148             $n++;
 149             if($argument_documentation ne "") {
 150                 if($argument_documentation !~ /^\/\*\s+\[(?:in|out|in\/out|\?\?\?)\].*?\*\/$/s) {
 151                     $output->write("argument $n documentation: \\\n$argument_documentation\n");
 152                 }
 153             }
 154         }
 155     }
 156 }
 157
 158 sub report_documentation {
 159     my $options = shift;
 160     my $output = shift;
 161
 162     if($options->documentation_comment_indent) {
 163         foreach my $indent (sort(keys(%comment_indent))) {
 164             my $count = $comment_indent{$indent};
 165             $output->write("*.c: $count functions have comment that is indented $indent\n");
 166         }
 167     }
 168
 169     if($options->documentation_comment_width) {
 170         foreach my $width (sort(keys(%comment_width))) {
 171             my $count = $comment_width{$width};
 172             $output->write("*.c: $count functions have comments of width $width\n");
 173         }
 174     }
 175 }
 176
 177 1;