Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Doxygen::Filter::Perl(User Contributed Perl DocumentatDoxygen::Filter::Perl(3)

       Doxygen::Filter::Perl - A perl code pre-filter for Doxygen

       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 POD
       (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

       Install Doxygen::Filter::Perl via CPAN or from source.  If you install
       from source then	do:

	   perl	Makefile.PL
	   make	install

       Make sure that the doxygen-filter-perl script was copied	from this
       project into your path somewhere	and that it has	RX permissions.


       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:


       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:

	   /home/jordan/workspace/PerlDoxygen/trunk/> doxygen Doxyfile

       All of your documentation will be in the	./doc/html/ directory inside
       of your project root.

       The following Doxygen style comment is the preferred block style,
       though others are supported and are listed below:

	   # ........

       You can also start comment blocks with "##" 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 "#"	comment	markers	as a blank line	can be used as
       a termination mark for the doxygen comment block.

       In other	languages the Doxygen @fn 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
       @method and @function structural	indicator so that they can be
       documented seperatly.

   Supported Structural	Indicators
	   #** @file [filename]
	   # ........

	   #** @class [class name (ex. Doxygen::Filter::Perl)]
	   # ........

	   #** @method or @function [public|private] [method-name] (parameters)
	   # ........

	   #** @attr or	@var [attribute-name] [brief description]
	   # ........

	   #** @section	[section-name] [section-title]
	   # ........

	   #** @brief [notes]
	   # ........

   Support Style Options and Section Indicators
       All doxygen style options and section indicators	are supported inside
       the structural indicators that we currently support.

   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 "_" 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:

	   #** @function [public|private] 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|private]	method-name (parameters)
	   # @brief A brief description	of the method
	   # A detailed	description of the method
	   # @params value [required|optional] [details]
	   # @retval value [details]
	   # ....

       The parameters would normally be	something like $foo, @bar, or %foobar.
       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:

	   #** @method public ProcessDataValues	($$sFile, %$hDataValues)

   Function / Method Example
	   sub test1
	       #** @method public test1	($value)
	       # ....

	   #** @method public test2 ($value)
	   # ....
	   sub test2


	   $self->{'_hData'}->{'filename'}->{'fullpath'}   = string
	   $self->{'_hData'}->{'filename'}->{'shortname'}  = string
	   $self->{'_hData'}->{'filename'}->{'version'}	   = string
	   $self->{'_hData'}->{'filename'}->{'details'}	   = string
	   $self->{'_hData'}->{'includes'}		   = array

	   $self->{'_hData'}->{'class'}->{'classorder'}		       = array
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutineorder'} = array
	   $self->{'_hData'}->{'class'}->{$class}->{'attributeorder'}  = array
	   $self->{'_hData'}->{'class'}->{$class}->{'details'}	       = string
	   $self->{'_hData'}->{'class'}->{$class}->{'comments'}	       = string

	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'type'}	       = string	(method	/ function)
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'state'}       = string	(public	/ private)
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'parameters'}  = string	(method	/ function parameters)
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'code'}	       = string
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'length'}      = integer
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'details'}     = string
	   $self->{'_hData'}->{'class'}->{$class}->{'subroutines'}->{$method}->{'comments'}    = string

	   $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$variable}->{'state'}      = string	(public	/ private)
	   $self->{'_hData'}->{'class'}->{$class}->{'attributes'}->{$variable}->{'comments'}   = string

       Bret Jordan <jordan at open1x littledot org> or <jordan2175 at gmail
       littledot com>

       Doxygen::Filter::Perl is	dual licensed GPLv3 and	Commerical. See	the
       LICENSE file for	more details.

perl v5.32.0			  2013-09-23	      Doxygen::Filter::Perl(3)


Want to link to this manual page? Use this URL:

home | help