doc/tools/find-tinyDescription

   1 #!/usr/bin/perl -w
   2 use strict;
   3 use File::Find ();
   4
   5 # -----------------------------------------------------------------------------
   6 #
   7 # Script
   8 #     find-tinyDescription
   9 #
  10 # Description
  11 #     Search for *.[H] files with 'Class' starting in the first column
  12 #     and a missing Description, or a tiny Description.
  13 #     A tiny Description is less than XX letters and does not resemble
  14 #     the class name. We'll look for descriptions matching the class name
  15 #     in a later pass.
  16 #
  17 #     - print filename '#' and the description
  18 #
  19 # -----------------------------------------------------------------------------
  20
  21 my $minLength   = 16;
  22 my $re_filespec = qr{^.+\.[H]$};
  23
  24 # for the convenience of &wanted calls, including -eval statements:
  25 ## use vars qw( *name *dir *prune );
  26 ## *name   = *File::Find::name;
  27 ## *dir    = *File::Find::dir;
  28 ## *prune  = *File::Find::prune;
  29
  30 sub wanted {
  31     unless ( lstat($_) and -f _ and -r _ and not -l _ and /$re_filespec/ ) {
  32         return;
  33     }
  34
  35     my ( $currentClass, $description );
  36
  37     local @ARGV = $_;
  38     while (<>) {
  39         my $name;
  40
  41         ## examine the class name
  42         if (/^Class\s*$/) {
  43             $_ = <>;
  44             ($currentClass) = split;
  45         }
  46         if (/^Description\s*$/) {
  47             $_ = <>;
  48             ( $description = $_ ) =~ s{^\s+|\s+$}{}g;
  49
  50             # remove trailing punctuation as being noise
  51             $description =~ s{\s*[.,:]+$}{};
  52             last;
  53         }
  54     }
  55
  56     $description ||= '';
  57
  58     ## we have 'Class' tag
  59     if ( defined $currentClass ) {
  60         # description doesnt looks like a class name
  61         if (
  62             $description !~ m{^\w+(::\w+)+$}
  63             and
  64             (length $description < $minLength or $description =~ m{^\S+$})
  65         ) {
  66             print "$File::Find::name # $description\n";
  67         }
  68     }
  69 }
  70
  71 ## Traverse desired filesystems
  72 for my $dir (@ARGV) {
  73     no warnings 'File::Find';
  74     warn "(**) checking '$dir' ...\n";
  75     File::Find::find( { wanted => \&wanted }, $dir );
  76 }
  77