1#!/usr/bin/env 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#
11# Copyright The Mbed TLS Contributors
12# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
13
14use warnings;
15use strict;
16use File::Basename;
17
18# C/header files in the following directories will be checked
19my @directories = qw(include/mbedtls library doxygen/input);
20
21# very naive pattern to find directives:
22# everything with a backslach except '\0' and backslash at EOL
23my $doxy_re = qr/\\(?!0|\n)/;
24
25# Return an error code to the environment if a potential error in the
26# source code is found.
27my $exit_code = 0;
28
29sub check_file {
30    my ($fname) = @_;
31    open my $fh, '<', $fname or die "Failed to open '$fname': $!\n";
32
33    # first line of the last normal comment block,
34    # or 0 if not in a normal comment block
35    my $block_start = 0;
36    while (my $line = <$fh>) {
37        $block_start = $.   if $line =~ m/\/\*(?![*!])/;
38        $block_start = 0    if $line =~ m/\*\//;
39        if ($block_start and $line =~ m/$doxy_re/) {
40            print "$fname:$block_start: directive on line $.\n";
41            $block_start = 0; # report only one directive per block
42            $exit_code = 1;
43        }
44    }
45
46    close $fh;
47}
48
49sub check_dir {
50    my ($dirname) = @_;
51    for my $file (<$dirname/*.[ch]>) {
52        check_file($file);
53    }
54}
55
56# Check that the script is being run from the project's root directory.
57for my $dir (@directories) {
58    if (! -d $dir) {
59        die "This script must be run from the Mbed TLS root directory";
60    } else {
61        check_dir($dir)
62    }
63}
64
65exit $exit_code;
66
67__END__
68