doc/percentdoc.pl

   1 #!/usr/bin/perl
   2 # A script to calculate the number and percentage of entities and functions
   3 # that are documented (with Doxygen documentation comments).
   4 #
   5 # It operates by parsing the output of Doxygen. It could break for different
   6 # versions of Doxygen -- it is known to work with version 1.5.5.
   7 #
   8 # Written by DWK
   9
  10 use strict;
  11 use warnings;
  12
  13 &process_files('html/*_8c.html');
  14
  15 sub process_files {
  16     my $pattern = shift;
  17     my %total = &new_list();
  18
  19     &print_header();
  20
  21     foreach my $file (glob $pattern) {
  22         my ($srcfile, %count) = &parse_file($file);
  23         &print_line($srcfile, %count);
  24
  25         foreach my $group (keys %total) {
  26             $total{$group}->{'total'} += $count{$group}->{'total'};
  27             $total{$group}->{'documented'} += $count{$group}->{'documented'};
  28         }
  29     }
  30
  31     &print_line("    *** Total ***", %total);
  32 }
  33
  34 sub new_list {
  35     my %list = (
  36         'all' => {'documented' => 0, 'total' => 0},
  37         'static' => {'documented' => 0, 'total' => 0},
  38         'normal' => {'documented' => 0, 'total' => 0}
  39     );
  40
  41     return %list;
  42 }
  43
  44 sub parse_file {
  45     my $file = shift;
  46     my $line = '';
  47     my $srcfile = '';
  48     my $mode = 'initial';
  49     my $name = '';
  50     my $section = '';
  51
  52     my %count = &new_list();
  53
  54     open(FILE, "<$file");
  55
  56     while($line = <FILE>) {
  57         chomp($line);
  58
  59         if($line =~ m|^<title>\w+: (.*) File Reference</title>$|) {
  60             $srcfile = $1;
  61         }
  62         elsif($line =~ m|^<hr><h2>(\w+) Documentation</h2>$|) {
  63             $section = $1;
  64         }
  65
  66         if($mode eq 'initial') {
  67             if($line eq '<div class="memproto">') {
  68                 $mode = 'findname';
  69             }
  70         }
  71         elsif($mode eq 'findname') {
  72             if($line =~ m|<td class="memname">([^<]+)|) {
  73                 $name = $1;
  74                 $name =~ s/^\s+//;
  75                 $name =~ s/\s+$//;
  76
  77                 $mode = 'finddoc';
  78             }
  79         }
  80         elsif($mode eq 'finddoc') {
  81             if($line eq '<div class="memdoc">') {
  82                 $mode = 'findp';
  83             }
  84         }
  85         elsif($mode eq 'findp') {
  86             if($line eq '<p>') {
  87                 $mode = 'findline';
  88             }
  89         }
  90         elsif($mode eq 'findline') {
  91             my $documented = 0;
  92             if($line =~ /\S/) {
  93                 $documented = 1;
  94             }
  95
  96             $count{'all'}->{'total'} ++;
  97             $count{'all'}->{'documented'} ++ if $documented;
  98
  99             if($section eq 'Function') {
 100                 if($name =~ /^static/) {
 101                     $count{'static'}->{'total'} ++;
 102                     $count{'static'}->{'documented'} ++ if $documented;
 103                 }
 104                 else {
 105                     $count{'normal'}->{'total'} ++;
 106                     $count{'normal'}->{'documented'} ++ if $documented;
 107                 }
 108             }
 109
 110             $mode = 'initial';
 111         }
 112     }
 113
 114     close(FILE);
 115
 116     return ($srcfile, %count);
 117 }
 118
 119 sub print_header {
 120     print "    *** Number and percentage of entities and functions "
 121         . "that are documented ***\n";
 122     printf("%-25s | %-15s | %-15s | %-15s\n",
 123         "Source file name", "All entities", "Normal funcs", "Static funcs");
 124 }
 125
 126 sub print_line {
 127     my $file = shift;
 128     my %count = @_;
 129
 130     printf("%-25s", $file);
 131
 132     # Do not use a foreach loop because a specific order is desired
 133     &print_group('all', %count);
 134     &print_group('normal', %count);
 135     &print_group('static', %count);
 136
 137     print "\n";
 138 }
 139
 140 sub print_group {
 141     my $group = shift;
 142     my %count = @_;
 143
 144     printf(" | %3d/%3d",
 145         $count{$group}->{'documented'}, $count{$group}->{'total'});
 146     if($count{$group}->{'total'}) {
 147         printf(" %6.2f%%",
 148             $count{$group}->{'documented'} / $count{$group}->{'total'}
 149                 * 100.0);
 150     }
 151     else {
 152         print " 100.00%";
 153     }
 154 }