.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Doxygen::Filter::Perl 3pm" .TH Doxygen::Filter::Perl 3pm "2020-12-29" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Doxygen::Filter::Perl \- A perl code pre\-filter for Doxygen .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Doxygen::Filter::Perl module is designed to provide support for documenting perl scripts and modules to be used with the Doxygen engine. We plan on supporting most Doxygen style comments and \s-1POD\s0 (plain old documentation) style comments. The Doxgyen style comment blocks for methods/functions can be inside or outside the method/function. Doxygen::Filter::Perl is hosted at http://perldoxygen.sourceforge.net/ .SH "USAGE" .IX Header "USAGE" Install Doxygen::Filter::Perl via \s-1CPAN\s0 or from source. If you install from source then do: .PP .Vb 3 \& perl Makefile.PL \& make \& make install .Ve .PP Make sure that the doxygen-filter-perl script was copied from this project into your path somewhere and that it has \s-1RX\s0 permissions. Example: .PP .Vb 1 \& /usr/local/bin/doxygen\-filter\-perl .Ve .PP Copy over the Doxyfile file from this project into the root directory of your project so that it is at the same level as your lib directory. This file will have all of the presets needed for documenting Perl code. You can edit this file with the doxywizard tool if you so desire or if you need to change the lib directory location or the output location (the default output is ./doc). Please see the Doxygen manual for information on how to configure the Doxyfile via a text editor or with the doxywizard tool. Example: .PP .Vb 2 \& /home/jordan/workspace/PerlDoxygen/trunk/Doxyfile \& /home/jordan/workspace/PerlDoxygen/trunk/lib/Doxygen/Filter/Perl.pm .Ve .PP Once you have done this you can simply run the following from the root of your project to document your Perl scripts or methods. Example: .PP .Vb 1 \& /home/jordan/workspace/PerlDoxygen/trunk/> doxygen Doxyfile .Ve .PP All of your documentation will be in the ./doc/html/ directory inside of your project root. .SH "DOXYGEN SUPPORT" .IX Header "DOXYGEN SUPPORT" The following Doxygen style comment is the preferred block style, though others are supported and are listed below: .PP .Vb 3 \& #** \& # ........ \& #* .Ve .PP You can also start comment blocks with \*(L"##\*(R" and end comment blocks with a blank line or real code, this allows you to place comments right next to the subroutines that they refer to if you wish. A comment block must have continuous \*(L"#\*(R" comment markers as a blank line can be used as a termination mark for the doxygen comment block. .PP In other languages the Doxygen \f(CW@fn\fR structural indicator is used to document subroutines/functions/methods and the parsing engine figures out what is what. In Perl that is a lot harder to do so I have added a \f(CW@method\fR and \f(CW@function\fR structural indicator so that they can be documented seperatly. .SS "Supported Structural Indicators" .IX Subsection "Supported Structural Indicators" .Vb 3 \& #** @file [filename] \& # ........ \& #* \& \& #** @class [class name (ex. Doxygen::Filter::Perl)] \& # ........ \& #* \& \& #** @method or @function [public|protected|private] [method\-name] (parameters) \& # ........ \& #* \& \& #** @attr or @var [public|protected|private] [type] {$%@}[attribute\-name] [brief description] \& # ........ \& #* \& \& #** @section [section\-name] [section\-title] \& # ........ \& #* \& \& #** @brief [notes] \& # ........ \& #* .Ve .SS "Support Style Options and Section Indicators" .IX Subsection "Support Style Options and Section Indicators" All doxygen style options and section indicators are supported inside the structural indicators that we currently support. .SS "Documenting Subroutines/Functions/Methods" .IX Subsection "Documenting Subroutines/Functions/Methods" The Doxygen style comment blocks that describe a function or method can exist before, after, or inside the subroutine that it is describing. Examples are listed below. It is also important to note that you can leave the public/private out and the filter will guess based on the subroutine name. The normal convention in other languages like C is to have the function/method start with an \*(L"_\*(R" if it is private/protected. We do the same thing here even though there is really no such thing in Perl. The whole reason for this is to help users of the code know what functions they should call directly and which they should not. The generic documentation blocks for functions and methods look like: .PP .Vb 8 \& #** @function [public|protected|private] [return\-type] function\-name (parameters) \& # @brief A brief description of the function \& # \& # A detailed description of the function \& # @params value [required|optional] [details] \& # @retval value [details] \& # .... \& #* \& \& #** @method [public|protected|private] [return\-type] method\-name (parameters) \& # @brief A brief description of the method \& # \& # A detailed description of the method \& # @params value [required|optional] [details] \& # @retval value [details] \& # .... \& #* .Ve .PP The parameters would normally be something like \f(CW$foo\fR, \f(CW@bar\fR, or \f(CW%foobar\fR. I have also added support for scalar, array, and hash references and those would be documented as $$foo, @$bar, %$foobar. An example would look this: .PP .Vb 1 \& #** @method public ProcessDataValues ($$sFile, %$hDataValues) .Ve .SS "Function / Method Example" .IX Subsection "Function / Method Example" .Vb 6 \& sub test1 \& { \& #** @method public test1 ($value) \& # .... \& #* \& } \& \& #** @method public test2 ($value) \& # .... \& #* \& sub test2 \& { \& \& } .Ve .SH "DATA STRUCTURE" .IX Header "DATA STRUCTURE" .Vb 5 \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqfilename\*(Aq}\->{\*(Aqfullpath\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqfilename\*(Aq}\->{\*(Aqshortname\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqfilename\*(Aq}\->{\*(Aqversion\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqfilename\*(Aq}\->{\*(Aqdetails\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqincludes\*(Aq} = array \& \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{\*(Aqclassorder\*(Aq} = array \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutineorder\*(Aq} = array \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqattributeorder\*(Aq} = array \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqdetails\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqcomments\*(Aq} = string \& \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqtype\*(Aq} = string (method / function) \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqreturntype\*(Aq} = string (return type) \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqstate\*(Aq} = string (public / private) \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqparameters\*(Aq} = string (method / function parameters) \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqcode\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqlength\*(Aq} = integer \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqdetails\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqsubroutines\*(Aq}\->{$method}\->{\*(Aqcomments\*(Aq} = string \& \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqattributes\*(Aq}\->{$variable}\->{\*(Aqstate\*(Aq} = string (public / private) \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqattributes\*(Aq}\->{$variable}\->{\*(Aqmodifiers\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqattributes\*(Aq}\->{$variable}\->{\*(Aqcomments\*(Aq} = string \& $self\->{\*(Aq_hData\*(Aq}\->{\*(Aqclass\*(Aq}\->{$class}\->{\*(Aqattributes\*(Aq}\->{$variable}\->{\*(Aqdetails\*(Aq} = string .Ve .SH "AUTHOR" .IX Header "AUTHOR" Bret Jordan or .SH "LICENSE" .IX Header "LICENSE" Doxygen::Filter::Perl is licensed with an Apache 2 license. See the \s-1LICENSE\s0 file for more details.