Skip to content

Commit

Permalink
doxify: cleanup scripts
Browse files Browse the repository at this point in the history
  • Loading branch information
@dev-zero
dev-zero committed Sep 30, 2019
1 parent 4c5ad5b commit 00994b2
Show file tree
Hide file tree
Showing 5 changed files with 215 additions and 189 deletions.
46 changes: 21 additions & 25 deletions tools/doxify/doxify.sh
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,40 @@
#!/bin/bash

DEBUG=0 # Set to 0 for no debugging, 1 for debugging
ARGS=${ARGS:-} # Set to "-v" for debugging
SCRIPTDIR=$(cd $(dirname "$0"); pwd) # Pick up full path to scripts from wherever doxify.sh lives

for file in "$@"; do
nwarnings=0

if $(python $SCRIPTDIR/is_fypp.py $file) ; then exit 0; fi
for file in "$@"; do
"${SCRIPTDIR}/is_fypp.py" "${file}" && continue

# generate temp-file names
tmp_file1=`mktemp`
tmp_file2=`mktemp`
tmp_file3=`mktemp`

# First apply the pre-processing script to get rid of any double & type lines
$SCRIPTDIR/remove_double_ampersands.pl $file $tmp_file1 $DEBUG
tmp_file=`mktemp`

# Run the fixcomments.pl script. This adds comment blocks to any subroutine/function
# definitions that don't have any and checks that existing comments are complete,
# fixing these if required.
$SCRIPTDIR/fixcomments.pl $tmp_file1 $tmp_file2 $DEBUG

# After adding comments, remove any double comment header lines
$SCRIPTDIR/remove_extra_comments.pl $tmp_file2 $tmp_file3 $DEBUG
# * First apply the pre-processing script to get rid of any double & type lines
# * Run the fixcomments.pl script. This adds comment blocks to any subroutine/function
# definitions that don't have any and checks that existing comments are complete,
# fixing these if required.
# * After adding comments, remove any double comment header lines
"${SCRIPTDIR}/remove_double_ampersands.pl" ${ARGS} "${file}" \
| "${SCRIPTDIR}/fixcomments.pl" ${ARGS} \
| "${SCRIPTDIR}/remove_extra_comments.pl" ${ARGS} > "${tmp_file}"

# Copy the final modified source file on top of the original file
if (! cmp -s $file $tmp_file3) ; then
cp $tmp_file3 $file
if ! cmp -s "${file}" "${tmp_file}" ; then
cp "${tmp_file}" "${file}"
fi

# Remove temp-files
rm -f $tmp_file1 $tmp_file2 $tmp_file3
# Remove temp-file
rm -f "${tmp_file}"

if grep -e "UNMATCHED_PROCEDURE_ARGUMENT" \
-e "UNKNOWN_DOXYGEN_COMMENT" \
-e "UNKNOWN_COMMENT" \
$file ; then
echo "Found doxify warnings in $file"
exit 42
"${file}" ; then
echo "Found doxify warnings in ${file}"
((nwarnings++))
fi

done

#EOF
exit ${nwarnings}
112 changes: 50 additions & 62 deletions tools/doxify/fixcomments.pl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,23 @@ =head1 NAME
=head1 SYNOPSIS
fixcomments.pl infile outfile [verbosity]
fixcomments.pl [options] [infile]
=head1 OPTIONS
=over 4
=item B<infile>
Input file to process.
Input file to process (uses stdin if not specified)
=item B<outfile>
=item B<--help|-h>
Output file to write after processing.
A little help
=item B<verbosity>
=item B<--verbose|-v>
Optional verbosity level: 0=quiet, 1=some info, 2=lots of info
Output debug messages (to stderr), repeat for even more output
=back
Expand All @@ -38,31 +38,25 @@ =head1 DESCRIPTION
use FindBin;
use lib "$FindBin::RealBin/lib";
use Pod::Usage qw(pod2usage);
use Getopt::Long;

# Check options
if ((@ARGV != 2) && (@ARGV != 3)) {
pod2usage(-verbose => 1, -message => "$0: Wrong number of arguments given.\n");
}
my $verbose = 0;
my $help = 0;

my $DBG=0;
if (defined($ARGV[2])) {
$DBG = $ARGV[2];
}
GetOptions(
'verbose+' => \$verbose,
'help|?' => \$help) or pod2usage(2);
pod2usage(1) if $help;

sub print_debug{
if($DBG>0){ print "DEBUG: @_\n";}
sub print_debug {
print(STDERR "DEBUG: @_\n") if ($verbose > 0);
}

print_debug("fixcomments.pl running with");
print_debug("Input: $ARGV[0]");
print_debug("Output: $ARGV[1]");

# Regular expressions for matching
my $DOXYGEN_HEADER = "^!>";

# The empty string
my ($EMPTY);
$EMPTY=q{};
my $EMPTY = q{};

# Toggle variables to keep track of which doxygen item is being processed
# in the current header.
Expand Down Expand Up @@ -125,11 +119,8 @@ sub print_debug{

initVariables();

open (my $INPUT , "<" , $ARGV[0]) or die("Cant open $ARGV[0] $!");
open (my $OUTPUT , ">" , $ARGV[1]) or die("Cant create $ARGV[1] $!");

# While there are still lines to read in our INPUT file
while (<$INPUT>) {
while (<>) {
# Get the line we've just read in
my $currline = $_;

Expand Down Expand Up @@ -163,7 +154,7 @@ sub print_debug{
# No header remaining so just print out line as read
print_debug("Empty old header, writing out line:");
print_debug($currline);
print $OUTPUT $currline;
print $currline;
} else {
# Header has been processed, need to do something with remaining lines
print_debug("Non-empty old header for line:");
Expand All @@ -181,19 +172,16 @@ sub print_debug{
# If it was a MODULE or TYPE header we still need to write
# it back out to file.
print_debug("Writing existing non FUNCTION/SUBROUTINE header to file");
print $OUTPUT $oldheader;
print $OUTPUT $leftoverlines;
print $OUTPUT $currline;
print $oldheader;
print $leftoverlines;
print $currline;
# Reset variables after output
initVariables();
}
}
} # End of the if (($currline is SUBROUTINE or FUNCTION ) block
} # End of main while loop

close $OUTPUT;
close $INPUT;

# Perhaps do a second pass to remove any double occurrences of !> *** type lines

sub initToggles {
Expand Down Expand Up @@ -478,7 +466,7 @@ sub processDoxygenHeader {
}
}
# Get the next line in the header block
$currline = <$INPUT>;
$currline = <>;
} while ($currline =~ m/^\s*!/xms); # Rule as to when you have finished a header. Currently Anything beginning with !
return $currline;
} # End of header processing subroutine
Expand Down Expand Up @@ -562,13 +550,13 @@ sub processSubroutineDefinition {
# If the entry for this parameter is missing we use
# the standard text for a missing entry
print_debug("Missing entry for parameter $p, creating blank");
print $OUTPUT "!> \\param $p ...\n";
print "!> \\param $p ...\n";
} else {
print_debug("Using existing entry for parameter $p");
if ($params{$p} !~ m/\\param\s*(\w+|\[.*\]\s+\w+)\s*\n/xms ) {
# Entry must contain some text after the parameter name
print_debug("Using entry unchanged");
print $OUTPUT $params{$p};
print $params{$p};
} else {
if ($params{$p} =~ m/!>\s*\n$/x) {
# We need to guard against \param entries which have
Expand All @@ -581,11 +569,11 @@ sub processSubroutineDefinition {
$tmpString[0] = $tmpString[0] . " ...";
for (my $i = 0; $i < $tmpLen; $i++) {
# Re-add the carriage return to each line
print $OUTPUT "$tmpString[$i]\n";
print "$tmpString[$i]\n";
}
} else {
chomp($params{$p});
print $OUTPUT $params{$p}," ...\n";
print $params{$p}," ...\n";
}
}
}
Expand All @@ -601,11 +589,11 @@ sub processSubroutineDefinition {
}
if (($briefs eq $EMPTY) or ($briefs eq "!> \\brief\n")) {
# \brief does not exist or is present but empty - add text
print $OUTPUT "! **************************************************************************************************\n";
print $OUTPUT "!> \\brief ...\n";
print "! **************************************************************************************************\n";
print "!> \\brief ...\n";
} else {
# \brief exists and contains text
print $OUTPUT $briefs;
print $briefs;
}
} elsif ($p =~ m/RESULT/ixms) {
# Check to see if parameter is RESULT for a FUNCTION
Expand Down Expand Up @@ -636,9 +624,9 @@ sub processSubroutineDefinition {
# Must protect against updating an existing comment
# Get rid of \n so UNMATCHED* text can be appended on.
chomp($params{$paramName});
print $OUTPUT $params{$paramName} . " UNMATCHED_PROCEDURE_ARGUMENT: please check \n";
print $params{$paramName} . " UNMATCHED_PROCEDURE_ARGUMENT: please check \n";
} else {
print $OUTPUT $params{$paramName};
print $params{$paramName};
}
}
}
Expand All @@ -648,54 +636,54 @@ sub processSubroutineDefinition {
if (!($hasAmpersand)) {
if ($returns ne $EMPTY) {
# Print RESULT value first so that it should come straight after the \param definitions
print $OUTPUT $returns;
print $returns;
} else {
# Get return value from function name
if ($isFunction) {
print $OUTPUT "!> \\return ...\n";
print "!> \\return ...\n";
}
}
if ($retVals ne $EMPTY) {
# Print return values definitions second so that they come after any \return definitions
print $OUTPUT $retVals;
print $retVals;
}
if (($dates eq $EMPTY) || ($dates eq "!> \\date\n")) {
# dates entry empty or exists and contains no text
### print $OUTPUT "!> \\date MISSING_COMMENT: Unknown\n"; # Use this line if you want to add text to the entry
print $OUTPUT $dates;
### print "!> \\date MISSING_COMMENT: Unknown\n"; # Use this line if you want to add text to the entry
print $dates;
} else {
print $OUTPUT $dates;
print $dates;
}
if (($pars eq $EMPTY) || ($pars eq "!> \\par History\n")) {
# pars entry empty or exists but contains no text
### print $OUTPUT "!> \\par History\n"; # Use this line if you want to add text to the entry
### print $OUTPUT "!> MISSING_COMMENT: Unknown\n"; # Use this line if you want to add text to the entry
print $OUTPUT $pars;
### print "!> \\par History\n"; # Use this line if you want to add text to the entry
### print "!> MISSING_COMMENT: Unknown\n"; # Use this line if you want to add text to the entry
print $pars;
} else {
print $OUTPUT $pars;
print $pars;
}
if (($authors eq $EMPTY) || ($authors eq "!> \\author\n")) {
# authors empty or exists but contains no text
### print $OUTPUT "!> \\author MISSING_COMMENT: Unknown\n"; # Use this line if you want to add text to the entry
print $OUTPUT $authors;
### print "!> \\author MISSING_COMMENT: Unknown\n"; # Use this line if you want to add text to the entry
print $authors;
} else {
print $OUTPUT $authors;
print $authors;
}
if ($versions ne $EMPTY) {
print $OUTPUT $versions;
print $versions;
}
if ($randoms ne $EMPTY) {
print $OUTPUT $randoms;
print $randoms;
}
if ($notes ne $EMPTY){
print $OUTPUT $notes;
print $notes;
}
if ($remainders ne $EMPTY) {
# Dumps out whatever else remainded in the header (e.g. stuff begining !> without a \ or stuff beginning with just a !) for the SUBROUTINE/FUNCTION at the end
print $OUTPUT $remainders;
print $remainders;
}
print $OUTPUT "! **************************************************************************************************\n";
print $OUTPUT "$leftoverlines$buffer$currline";
print "! **************************************************************************************************\n";
print "$leftoverlines$buffer$currline";
# Reset all the variables after writing out the header
initVariables();
return;
Expand Down
7 changes: 4 additions & 3 deletions tools/doxify/is_fypp.py
100644 → 100755
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
#!/usr/bin/env python

import sys, re

FYPP_SYMBOLS = r"(#|\$|@)"
FYPP_LINE = r"^\s*" + FYPP_SYMBOLS + r":"
FYPP_INLINE = r"(" + FYPP_SYMBOLS + r"{|}" + FYPP_SYMBOLS + r")"
FYPP_RE = re.compile(r"(" + FYPP_LINE + r"|" + FYPP_INLINE + r")")

infile = open(sys.argv[1], 'r')
for line in infile.readlines():
if FYPP_RE.search(line):
with open(sys.argv[1], "r") as infile:
if any(FYPP_RE.search(l) for l in infile):
sys.exit(0)

sys.exit(1)

0 comments on commit 00994b2

Please sign in to comment.