1#!/usr/bin/perl
2
3# Detect comment blocks that are likely meant to be doxygen blocks but aren't.
4#
5# More precisely, look for normal comment block containing '\'.
6# Of course one could use doxygen warnings, eg with:
7#   sed -e '/EXTRACT/s/YES/NO/' doxygen/mbedtls.doxyfile | doxygen -
8# but that would warn about any undocumented item, while our goal is to find
9# items that are documented, but not marked as such by mistake.
10
11use warnings;
12use strict;
13use File::Basename;
14
15# C/header files in the following directories will be checked
16my @directories = qw(include/mbedtls library doxygen/input);
17
18# very naive pattern to find directives:
19# everything with a backslach except '\0' and backslash at EOL
20my $doxy_re = qr/\\(?!0|\n)/;
21
22sub check_file {
23    my ($fname) = @_;
24    open my $fh, '<', $fname or die "Failed to open '$fname': $!\n";
25
26    # first line of the last normal comment block,
27    # or 0 if not in a normal comment block
28    my $block_start = 0;
29    while (my $line = <$fh>) {
30        $block_start = $.   if $line =~ m/\/\*(?![*!])/;
31        $block_start = 0    if $line =~ m/\*\//;
32        if ($block_start and $line =~ m/$doxy_re/) {
33            print "$fname:$block_start: directive on line $.\n";
34            $block_start = 0; # report only one directive per block
35        }
36    }
37
38    close $fh;
39}
40
41sub check_dir {
42    my ($dirname) = @_;
43    for my $file (<$dirname/*.[ch]>) {
44        check_file($file);
45    }
46}
47
48# locate root directory based on invocation name
49my $root = dirname($0) . '/..';
50chdir $root or die "Can't chdir to '$root': $!\n";
51
52# just do it
53for my $dir (@directories) {
54    check_dir($dir)
55}
56
57__END__
58