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# 14# This file is provided under the Apache License 2.0, or the 15# GNU General Public License v2.0 or later. 16# 17# ********** 18# Apache License 2.0: 19# 20# Licensed under the Apache License, Version 2.0 (the "License"); you may 21# not use this file except in compliance with the License. 22# You may obtain a copy of the License at 23# 24# http://www.apache.org/licenses/LICENSE-2.0 25# 26# Unless required by applicable law or agreed to in writing, software 27# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 28# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29# See the License for the specific language governing permissions and 30# limitations under the License. 31# 32# ********** 33# 34# ********** 35# GNU General Public License v2.0 or later: 36# 37# This program is free software; you can redistribute it and/or modify 38# it under the terms of the GNU General Public License as published by 39# the Free Software Foundation; either version 2 of the License, or 40# (at your option) any later version. 41# 42# This program is distributed in the hope that it will be useful, 43# but WITHOUT ANY WARRANTY; without even the implied warranty of 44# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 45# GNU General Public License for more details. 46# 47# You should have received a copy of the GNU General Public License along 48# with this program; if not, write to the Free Software Foundation, Inc., 49# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 50# 51# ********** 52 53use warnings; 54use strict; 55use File::Basename; 56 57# C/header files in the following directories will be checked 58my @directories = qw(include/mbedtls library doxygen/input); 59 60# very naive pattern to find directives: 61# everything with a backslach except '\0' and backslash at EOL 62my $doxy_re = qr/\\(?!0|\n)/; 63 64# Return an error code to the environment if a potential error in the 65# source code is found. 66my $exit_code = 0; 67 68sub check_file { 69 my ($fname) = @_; 70 open my $fh, '<', $fname or die "Failed to open '$fname': $!\n"; 71 72 # first line of the last normal comment block, 73 # or 0 if not in a normal comment block 74 my $block_start = 0; 75 while (my $line = <$fh>) { 76 $block_start = $. if $line =~ m/\/\*(?![*!])/; 77 $block_start = 0 if $line =~ m/\*\//; 78 if ($block_start and $line =~ m/$doxy_re/) { 79 print "$fname:$block_start: directive on line $.\n"; 80 $block_start = 0; # report only one directive per block 81 $exit_code = 1; 82 } 83 } 84 85 close $fh; 86} 87 88sub check_dir { 89 my ($dirname) = @_; 90 for my $file (<$dirname/*.[ch]>) { 91 check_file($file); 92 } 93} 94 95# Check that the script is being run from the project's root directory. 96for my $dir (@directories) { 97 if (! -d $dir) { 98 die "This script must be run from the mbed TLS root directory"; 99 } else { 100 check_dir($dir) 101 } 102} 103 104exit $exit_code; 105 106__END__ 107