Documentation Generator for Perl

After trying several different documentation generators for Perl, I found Perl Doxygen to be the best for several reasons:

  • Doc output customization
  • Distinguishes methods and functions from each other
  • Similar to javadoc
  • Nice looking GUI

To use Doxygen for Perl, you will need to have both Doxygen and PerlDoxygen installed, which is available at sourceforge.net.

Once both are installed, you can customize your documentation using the tags inside the ‘Doxyfile’ config file. This file is located inside the directory you installed Doxygen.
Copy this file into your project’s main folder and open it with your editor of choice.

Useful Tags to configure:

    • PROJECT_NAME = your project name
    • PROJECT_BRIEF = brief one line project description
    • INPUT = relative path to scripts/modules
    • EXTRACT_ALL = YES
    • EXTRACT_PRIVATE = YES
    • EXTRACT_STATIC = YES

(EXTRACT tags are to ensure all variables are included in your documentation)

Documentation
Syntax:

#**start of documentation block
#*end of documentation block


#** 
#
#
#* 

Script/Module (top of the file):


#** @file script/module name
# @brief Summary of script/module
# @verbatim
# ... 
# ...
# @endverbatim
# @author Len Isac - https://lenisac.wordpress.com
# @copy copyright
#*

Methods/Functions (can go above or inside method/function):


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

}

Once your config file is set to your project’s needs and your code is documented using the comment styles above, you can run doxygen Doxyfile from the command-line (inside your project’s main folder).

I’ve set the INPUT tag to the current folder (.), that way doxygen will search recursively through the current project’s directories and output the generated html documentation to the ‘doc’ folder by default (you can also customize this to your preference using the OUTPUT_DIRECTORY tag).

You can open the doc/index.html file to view your documentation.

Advertisements