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
13#
14# Licensed under the Apache License, Version 2.0 (the "License"); you may
15# not use this file except in compliance with the License.
16# You may obtain a copy of the License at
17#
18# http://www.apache.org/licenses/LICENSE-2.0
19#
20# Unless required by applicable law or agreed to in writing, software
21# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
22# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
23# See the License for the specific language governing permissions and
24# limitations under the License.
25
26use warnings;
27use strict;
28use File::Basename;
29
30# C/header files in the following directories will be checked
31my @directories = qw(include/mbedtls library doxygen/input);
32
33# very naive pattern to find directives:
34# everything with a backslach except '\0' and backslash at EOL
35my $doxy_re = qr/\\(?!0|\n)/;
36
37# Return an error code to the environment if a potential error in the
38# source code is found.
39my $exit_code = 0;
40
41sub check_file {
42    my ($fname) = @_;
43    open my $fh, '<', $fname or die "Failed to open '$fname': $!\n";
44
45    # first line of the last normal comment block,
46    # or 0 if not in a normal comment block
47    my $block_start = 0;
48    while (my $line = <$fh>) {
49        $block_start = $.   if $line =~ m/\/\*(?![*!])/;
50        $block_start = 0    if $line =~ m/\*\//;
51        if ($block_start and $line =~ m/$doxy_re/) {
52            print "$fname:$block_start: directive on line $.\n";
53            $block_start = 0; # report only one directive per block
54            $exit_code = 1;
55        }
56    }
57
58    close $fh;
59}
60
61sub check_dir {
62    my ($dirname) = @_;
63    for my $file (<$dirname/*.[ch]>) {
64        check_file($file);
65    }
66}
67
68# Check that the script is being run from the project's root directory.
69for my $dir (@directories) {
70    if (! -d $dir) {
71        die "This script must be run from the mbed TLS root directory";
72    } else {
73        check_dir($dir)
74    }
75}
76
77exit $exit_code;
78
79__END__
80