From f571c5950bfe476ef79d4c143f50e2f9e0d5edc7 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Sun, 5 Aug 2018 00:12:54 -0500 Subject: [PATCH] Modify DBD processing scripts to output Doxygen comments --- modules/database/src/tools/DBD/Menu.pm | 5 ++++- modules/database/src/tools/DBD/Recfield.pm | 6 +++--- modules/database/src/tools/DBD/Recordtype.pm | 13 +++++++++---- modules/database/src/tools/dbdToMenuH.pl | 6 +++++- modules/database/src/tools/dbdToRecordtypeH.pl | 12 +++++++++--- modules/database/test/tools/Menu.plt | 6 ++++-- 6 files changed, 34 insertions(+), 14 deletions(-) diff --git a/modules/database/src/tools/DBD/Menu.pm b/modules/database/src/tools/DBD/Menu.pm index 38a2aba99..5480b3952 100644 --- a/modules/database/src/tools/DBD/Menu.pm +++ b/modules/database/src/tools/DBD/Menu.pm @@ -67,13 +67,16 @@ sub toDeclaration { my $name = $this->name; my $macro_name = "${name}_NUM_CHOICES"; my @choices = map { - sprintf " %-31s /* %s */", @{$_}[0], escapeCcomment(@{$_}[1]); + sprintf " %-31s /**< \@brief State string \"%s\" */", + @{$_}[0], escapeCcomment(@{$_}[1]); } $this->choices; my $num = scalar @choices; return "#ifndef $macro_name\n" . + "/** \@brief Enumerated type from menu $name */\n" . "typedef enum {\n" . join(",\n", @choices) . "\n} $name;\n" . + "/** \@brief Number of states defined for menu $name */\n" . "#define $macro_name $num\n" . "#endif\n\n"; } diff --git a/modules/database/src/tools/DBD/Recfield.pm b/modules/database/src/tools/DBD/Recfield.pm index cc49bcc46..b4bd5d318 100644 --- a/modules/database/src/tools/DBD/Recfield.pm +++ b/modules/database/src/tools/DBD/Recfield.pm @@ -185,7 +185,7 @@ sub toDeclaration { my $name = $this->C_name; my $result = sprintf " %-19s %-12s", $ctype, "$name;"; my $prompt = $this->attribute('prompt'); - $result .= "/* $prompt */" if defined $prompt; + $result .= "/**< \@brief $prompt */" if defined $prompt; return $result; } @@ -217,7 +217,7 @@ sub toDeclaration { my $size = $this->attribute('size'); my $result = sprintf " %-19s %-12s", 'char', "${name}[${size}];"; my $prompt = $this->attribute('prompt'); - $result .= "/* $prompt */" if defined $prompt; + $result .= "/**< \@brief $prompt */" if defined $prompt; return $result; } @@ -540,7 +540,7 @@ sub toDeclaration { my $extra = $this->attribute('extra'); my $result = sprintf " %-31s ", "$extra;"; my $prompt = $this->attribute('prompt'); - $result .= "/* $prompt */" if defined $prompt; + $result .= "/**< \@brief $prompt */" if defined $prompt; return $result; } diff --git a/modules/database/src/tools/DBD/Recordtype.pm b/modules/database/src/tools/DBD/Recordtype.pm index a602f5da4..1e626fdf8 100644 --- a/modules/database/src/tools/DBD/Recordtype.pm +++ b/modules/database/src/tools/DBD/Recordtype.pm @@ -132,10 +132,15 @@ sub toDeclaration { $_->toDeclaration } $this->fields; my $name = $this->name; - $name .= "Record" unless $name eq "dbCommon"; - return "typedef struct $name {\n" . - join("\n", @fields) . - "\n} $name;\n\n"; + my $doc = $name; + if ($name ne 'dbCommon') { + $name .= 'Record'; + $doc .= ' record type.'; + } + return "/** \@brief Declaration of $doc */\n" . + "typedef struct $name {\n" . + join("\n", @fields) . + "\n} $name;\n\n"; } 1; diff --git a/modules/database/src/tools/dbdToMenuH.pl b/modules/database/src/tools/dbdToMenuH.pl index 10f1904fb..71352edff 100644 --- a/modules/database/src/tools/dbdToMenuH.pl +++ b/modules/database/src/tools/dbdToMenuH.pl @@ -11,6 +11,8 @@ use FindBin qw($Bin); use lib ("$Bin/../../lib/perl"); +use strict; + use EPICS::Getopts; use File::Basename; use DBD; @@ -57,7 +59,9 @@ if ($opt_D) { print map { "$_:\n" } @uniqfiles; } else { open OUTFILE, ">$outfile" or die "$tool: Can't open $outfile: $!\n"; - print OUTFILE "/* $outbase generated from $inbase */\n\n", + print OUTFILE "/** \@file $outbase\n", + " * \@brief Declarations generated from $inbase\n", + " */\n\n", "#ifndef $guard_name\n", "#define $guard_name\n\n"; my $menus = $dbd->menus; diff --git a/modules/database/src/tools/dbdToRecordtypeH.pl b/modules/database/src/tools/dbdToRecordtypeH.pl index 76bae7fbf..0bb3839fe 100644 --- a/modules/database/src/tools/dbdToRecordtypeH.pl +++ b/modules/database/src/tools/dbdToRecordtypeH.pl @@ -61,13 +61,19 @@ if ($opt_D) { # Output dependencies only, to stdout print "$outfile: ", join(" \\\n ", @uniqfiles), "\n\n"; print map { "$_:\n" } @uniqfiles; } else { + our ($rn, $rtyp) = each %{$rtypes}; + my $rtn = $rn; + $rtn .= 'Record' if $rn ne 'dbCommon'; + open OUTFILE, ">$outfile" or die "$tool: Can't open $outfile: $!\n"; - print OUTFILE "/* $outbase generated from $inbase */\n\n", + print OUTFILE "/** \@file $outbase\n", + " * \@brief Declarations for the \@ref $rtn \"$rn\" record type.\n", + " *\n", + " * This header was generated from $inbase\n", + " */\n\n", "#ifndef $guard_name\n", "#define $guard_name\n\n"; - our ($rn, $rtyp) = each %{$rtypes}; - print OUTFILE $rtyp->toCdefs; my @menu_fields = grep { diff --git a/modules/database/test/tools/Menu.plt b/modules/database/test/tools/Menu.plt index 25b0c2020..8e667c833 100644 --- a/modules/database/test/tools/Menu.plt +++ b/modules/database/test/tools/Menu.plt @@ -30,10 +30,12 @@ is_deeply $menu->choice(2), undef, 'Third choice undefined'; like $menu->toDeclaration, qr/ ^ \s* \# \s* ifndef \s+ test_NUM_CHOICES \s* \n + \s* \/\*\* [^*]* \*\/ \s* \n \s* typedef \s+ enum \s+ \{ \s* \n - \s* ch1 \s+ \/\* [^*]* \*\/, \s* \n - \s* ch2 \s+ \/\* [^*]* \*\/ \s* \n + \s* ch1 \s+ \/\*\* [^*]* \*\/, \s* \n + \s* ch2 \s+ \/\*\* [^*]* \*\/ \s* \n \s* \} \s* test \s* ; \s* \n + \s* \/\*\* [^*]* \*\/ \s* \n \s* \# \s* define \s+ test_NUM_CHOICES \s+ 2 \s* \n \s* \# \s* endif \s* \n \s* $ /x, 'C declaration';