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