Bug #640357: Adding very limited Perl-Support for doxygen

Adding Doxygen commands to the Perl-scripts in the sources

I searched for every *.pl file in the GnuCash source and added Doxygen commands
like @file, @brief, @author to better include them in doxygen.

Patch by Christoph Holtermann.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@20267 57a11ea4-9604-0410-9ed3-97b8803252fd

doc/examples/create-bogus-data.pl

@@ -1,12 +1,15 @@
 #! /usr/bin/env perl
 #
+## @file
+#
 # create-bogus-data.pl
 #
-# Create a lot of 'fake' transactions, handy for generating 
+# @brief Create a lot of 'fake' transactions, handy for generating 
 # large datasets for performance testing.
 # 
 # currently, very hacked up, uses hard-wired accounts
 # from the "txnreport.xac" test file
+#
 
 
 $ntrans = 3000;

src/backend/xml/test/grab-types.pl

@@ -1,5 +1,6 @@
 #!/usr/bin/perl -w
-
+##@file
+#@cond Perl
 use strict;
 
 my $tag = shift @ARGV;
@@ -49,3 +50,4 @@ while (<XMLFILE>) {
 }
 
 print $files_written
+##@endcond Perl

src/engine/xlate.pl

@@ -1,11 +1,15 @@
 #! /usr/bin/perl
-#
-# FUNCTION: this utility script converts old code to the new
-#           QOF routine names, and does other related cleanup
+##  @file
+#   @brief  
+#   FUNCTION: this utility script converts old code to the new
+#      	      QOF routine names, and does other related cleanup
 #
 # USAGE: ls *.c *.h | ./xlate.pl ; make ; cvs commit
 #        
 # AUTHOR: Linas Vepstas <linas@linas.org> June 2003
+# @author Linas Vepstas <linas@linas.org>
+# @date June 2003
+# @cond Perl
 
 @files = <STDIN>;
 
@@ -265,3 +269,4 @@ foreach (@files)
 	$rn = "mv " . $afile . ".tmp " . $afile;
 	system ($rn);
 }
+## @endcond Perl

src/experimental/cbb/cbb-engine/CBBlib.pl

@@ -6,38 +6,41 @@ package CBBlib;
 use strict;
 use English;
 use IO;
-
+##  @file
+# @brief Belongs to package CBBlib
+#
 #### To do ######################
-
+#
 # Check remove transactions.
 # Move everything to Cbb package.
-
+#
 # put warnings into add_txns and remove_txns if attempted when inside
 # begin/end_txn_modifications
-
+#
 # Check to see that set_db is OK in the face of modifications...
-
+#
 # update_ledger has to return a sorted list of txn indices for modified txns
-
+#
 # ledger_add/modify/remove_txns?
-
+#
 # note_txn_modification
-
+#
 # Dirty should be set whenever a modification is made.
 # Dirty should be cleared whenever the client tells us we're clear...
-
+#
 # What about clones and begin/end_modify_txns and no db?
-
+#
 # check copy_obj, and automate?
-
+#
 # Need to clone account balances too?
-
+#
 # Should have list positions in txns?
-
+#
 # Need to create "Unitemized" category by default.
-
+#
 # Don't sort modifications by serial number.  Order is irrelevant.
 # Just use dates
+# @cond Perl
 
 STDOUT->autoflush(1);
 STDERR->autoflush(1);
@@ -1733,3 +1736,4 @@ sub load_file {
 
 1;
 __END__
+## @endcond Perl

src/experimental/cbb/cbb-engine/common.pl

@@ -22,6 +22,13 @@
 # $Id$
 # (Log is kept at end of this file)
 
+## @file
+# @brief common routines shared by many CBB files 
+# @author Curtis Olson
+# @date Started August 22, 1994
+# @cond PERL
+# ignore the following for doxygen
+
 use strict;
 
 sub destructive_merge_mangle {
@@ -334,7 +341,7 @@ sub mypwd {
 1;        # need to return a true value
 __END__
 
-
+## @endcond
 # ----------------------------------------------------------------------------
 # $Log$
 # Revision 1.1  2000/06/02 09:00:14  peticolas

src/quotes/Quote_example.pl

@@ -1,8 +1,9 @@
 #!/usr/bin/perl -w
-#
+##@file
+# @brief
 # example script showing how to use the Quote perl module.
 # gets prices for some stocks, for some mutual funds
-
+#
 # Note that this example uses the meta-level "fetch" command.  We do
 # NOT used that in Gnucash because it's behavior is unpredictable If
 # the given method/exchange doesn't work, it'll fall back to other
@@ -11,6 +12,8 @@
 # directly, i.e. $quoter->fidelity_direct("IBM", "LNUX");, etc.  The
 # documentation page for each Finance::Quote sub-module describes how
 # to call it directly without fallbacks.
+#
+# @cond PERL
 
 use Finance::Quote;
 
@@ -84,3 +87,4 @@ foreach $f (@funds) {
 	      $quotes{$f,"date"}."\n";
 }
 print "\n\n";
+##@endcond Perl