check-doxy-blocks.pl (2453B)
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 use warnings; 15 use strict; 16 use File::Basename; 17 18 # C/header files in the following directories will be checked 19 my @mbedtls_directories = qw(include/mbedtls library doxygen/input); 20 my @tf_psa_crypto_directories = qw(include/psa include/tf-psa-crypto 21 include/mbedtls 22 drivers/builtin/include/mbedtls 23 drivers/builtin/src core doxygen/input); 24 25 # very naive pattern to find directives: 26 # everything with a backslach except '\0' and backslash at EOL 27 my $doxy_re = qr/\\(?!0|\n)/; 28 29 # Return an error code to the environment if a potential error in the 30 # source code is found. 31 my $exit_code = 0; 32 33 sub check_file { 34 my ($fname) = @_; 35 open my $fh, '<', $fname or die "Failed to open '$fname': $!\n"; 36 37 # first line of the last normal comment block, 38 # or 0 if not in a normal comment block 39 my $block_start = 0; 40 while (my $line = <$fh>) { 41 $block_start = $. if $line =~ m/\/\*(?![*!])/; 42 $block_start = 0 if $line =~ m/\*\//; 43 if ($block_start and $line =~ m/$doxy_re/) { 44 print "$fname:$block_start: directive on line $.\n"; 45 $block_start = 0; # report only one directive per block 46 $exit_code = 1; 47 } 48 } 49 50 close $fh; 51 } 52 53 sub check_dir { 54 my ($dirname) = @_; 55 for my $file (<$dirname/*.[ch]>) { 56 check_file($file); 57 } 58 } 59 60 open my $project_file, "scripts/project_name.txt" or die "This script must be run from Mbed TLS or TF-PSA-Crypto root directory"; 61 my $project = <$project_file>; 62 chomp($project); 63 my @directories; 64 65 if ($project eq "TF-PSA-Crypto") { 66 @directories = @tf_psa_crypto_directories 67 } elsif ($project eq "Mbed TLS") { 68 @directories = @mbedtls_directories 69 } 70 # Check that the script is being run from the project's root directory. 71 for my $dir (@directories) { 72 check_dir($dir) 73 } 74 75 exit $exit_code; 76 77 __END__