Modify DBD processing scripts to output Doxygen comments

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";
 }

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;
 }
 

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;

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;

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 {

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';