PS1-MOPS SOURCE CODE DOCUMENTATION
DRAFT
D. Chang Institute for Astronomy University of Hawaii at Manoa
An overview of using Doxygen to processed embedded documentation in PS1-MOPS Perl source code is provided. The goal is to be able to automatically generate documentation at the program/class-level and the subroutine-level. This may be accomplished using Doxygen and a filter specific to Perl as Doxygen does not natively support Perl. Example documented source code is provided along with actual Doxygen-generated HTML output.
INTRODUCTION This document provides an overview of using of Doxygen [1] for PS1-MOPS Perl source code. Doxygen does not have native support for Perl. However, it may be used to generate documentation from Perl code if the code is first preprocessed so that Doxygen-compatible input is produced. This is accomplished using a filter [2]. The source code may then contain commands that are analogues to Doxygen commands to produce an equivalent level of documentation from comments embedded in Perl source code. The initial benefit of this documentation creation method is a hyperlinked HTML API reference containing both module-level and subroutine-level documentation. The scope of this generated documentation is intended to span the range from the user-level to the programmer-level with an emphasis on documentation to support code maintenance and development. One of the most common documentation systems in use with Perl is POD (plain old documentation). The guidelines for Doxygen-compatible documentation are derived in large part from conventional implementations of POD. Use of Doxygen is intended to provide the same usability as POD but augmented by the added flexibility of Doxygen. The purpose is to develop a general method of documentation that applies to all aspects of PS1-MOPS programming. This is made possible by Doxygen.
PROGRAMMING ELEMENTS Source code follows the hierarchy of namespace, class, and subroutine. In Perl, namespaces are indicated by the directories that contain modules. Classes are, in general, the same as modules. Modules may also be called packages. Subroutines consist of either functions or object methods. These programming elements are common to all object-oriented programming languages. COMPARISON WITH POD Perl modules are often documented using POD format. Advantages of POD include programmer familiarity due to its ubiquity, usability with established tools such as perldoc, and overall simplicity in its implementation. While POD does not mandate a set of categories for which to include documentation, a number of common ones that are often addressed are listed below. For documentation of MOPS source code, it is suggested that embedded documentation cover the categories listed below thereby providing equal utility with conventional POD documentation. • NAME The name of the module that typically includes a brief description separated from the name by three characters: space, dash, space. • SYNOPSIS Includes examples of usage. • DESCRIPTION A detailed description of the module. • FUNCTIONS Subroutines that are not specific class methods. • METHODS Subroutines that are implemented by a specific class/object.
WRITING DOXYGEN-COMPATIBLE DOCUMENTATION IN PERL Doxygen does not natively support documentation in source code comments in Perl. However, Perl code documentation may be parsed by Doxygen by preprocessing the Perl code through a filter. The filter result, being in Doxygen-format, can then be parsed by Doxygen. The source code must contain commands recognizable by the filter. These commands, and how to format Perl code documentation so that is compatible with a Doxygen filter, are described henceforth.
PROGRAM/CLASS-LEVEL DOCUMENTATION Classes generally correspond to individual Perl modules. Executable Perl scripts are considered to be independent programs. Program/class-level documentation in the source code mostly corresponds to the kind of documentation that might be found in a manual page. It is intended to provide an overview of the class along with usage examples. The following list describes Doxygen filter commands for program/class-level documentation. Doxygen filter commands • ## @file Corresponds to Doxygen command \file. Used to describe the contents of a file. The filename should be listed here along with a brief description followed by a detailed description. This section maybe used to provide the POD content found under the headings: NAME, SYNOPSIS, and DESCRIPTION. • ## @class Corresponds to Doxygen command \class. Used to describe a class. The class name along with a detailed description should be defined here. Note that the classes specified using the @class command is the only way for Doxygen to identify classes. It is important that they be specified. • # @par Paragraphs may be created using the @par command. Note the @par command is preceded by a single hash mark. Text on the same line as the @par command will print as a header in the output.
PS1-MOPS Source Code Documentation 2 • # @note Text notated as note text. • # @see Provide comma-separated list of references to other items of relevance.
SUBROUTINE-LEVEL DOCUMENTATION Subroutines include both functions and methods. This level of documentation is intended to be comprehensive. Every function and method should include a basic set of documentation. Each subroutine name may be preceded with its access scope. Available scopes are public, private, and protected. Undefined scopes default to public. The primary set of Doxygen filter commands is listed below. Doxygen filter commands • ## @fn Corresponds to Doxygen command \fn. Used to describe a function including its parameters and return value. • ## @method Used to describe an object method. • ## @cmethod Used to describe a class method. • # @param Describe a parameter to a function. • # @return Describe the return value for a function/method.
VERSIONS Software versions are an essential documentation component. Versioning will be managed by CVS using the CVS tag $Revision: $. For Perl, the conventional $VERSION variable will be used. Many popular Perl programs, such as ExtUtils::MakeMaker or Module::Build, make use of this variable to determine module versions. To obtain a standard version number for Perl modules, typically having extension .pm, the following code [3] should be included in each module. our $VERSION = sprintf "%d.%d", q$Revision: $ =~ /(\d+)/g; When this code is committed to CVS, the version number will be placed after Revision:. For example, given a CVS revision of 1.1 the result in the source code will be our $VERSION = sprintf "%d.%d", q$Revision: 1.1$ =~ /(\d+)/g; When the module version needs to be referenced, it can be obtained using the following code. use module_name; $module_version = $module_name::VERSION; The variable $module_version will have the value 1.1. Perl executables, typically having extension .pl, cannot be imported using use, though they can be imported using require but this causes them to be executed which is generally not wanted. Therefore, an alternative method of version number retrieval will be used. Perl executable code should still contain the our $VERSION line defined previously. To make the CVS revision number available, executables should implement the command-line option --version so that the following statement will correctly retrieve the CVS revision number defined in the source code.
PS1-MOPS Source Code Documentation 3 $ executable_name.pl --version
USING DOXYGEN Use of Doxygen with Perl requires two files: a configuration file (doxy-config) and a filter configuration file (perl-doxy-config). The configuration files define the location of the source code to be processed along with the destination of the output. They also define various features of the output. The intention of using Doxygen with MOPS is to generate an HTML API reference. To specify a filter to be used by Doxygen, configure the following option: INPUT_FILTER = doxygenfilter Once the configuration files have proper definitions, Doxygen may be executed via the command-line using: $ doxygen perl-doxy-config
DOXYGEN HTML DOCUMENTATION FEATURES Some of the features present in Doxygen-generated HTML documentation are listed below. File list Contains all the files parsed by Doxygen. The files to be included are denoted by a pattern in the Perl Doxygen configuration file. Class list Only those items notated by @class will be included in this category. Source code Doxygen provides for viewing partially colorized source code directly in the HTML API reference. Formatted descriptions Formatting includes lists and emphasized text along with paragraphs and paragraph titles. Program/class-level descriptions are referenced through Doxygen file references found in the File list. Function/method documentation Information includes access scope, a description, parameters, and return values. Functions/methods are grouped by access scope.
AUTOMATIC DOCUMENTATION GENERATION The presence of properly formatted source code documentation allows for the automatic generation of a documentation set for the code. To facilitate current documentation for the MOPS code base, documentation will be extracted, formatted and updated on a nightly basis.
FUTURE WORK Doxygen has an extensive feature set and can serve extended purposes beyond those described herein. Some additional areas of documentation development are listed below. • Automatically determine missing documentation items for source code. • Tweak filter so that embedded commands have greater consistency in formatting. • Provide equivalent support for Python source code. • Implement more features of Doxygen such as call graphs and LaTeX documentation generation.
PS1-MOPS Source Code Documentation 4 CONCLUSION The guidelines presented in this document allow for documentation that serves a broad range of requirements for PS1-MOPS documentation. They allow for the generation of a comprehensive documentation set for MOPS source code with minimal programmer manual overhead. A useful, subset of the features of Doxygen have been described that facilitate the achievement of PS1-MOPS documentation goals.
PS1-MOPS Source Code Documentation 5 APPENDIX File example_perl_module.pm The following code lists an example Perl module containing embedded documentation along with Doxygen filter commands. package example_perl_module;
# Doxygen filter commands are preceded by ##.
## @file example-perl-module.pm # A sample Perl module with commands for Doxygen documentation. # @par DESCRIPTION # This is the start of the detailed description for the module. The brief # description may be seperated from the detailed description by an empty line. # Multiple lines may be present, but the first sentence or phrase, after the # filename, is considered to be the brief description for the file. # @par SYNOPSIS # One application of this feature is to replicate POD-style documentation. # Usage examples may appear here. # @par # Lists with bullets may be included. # - List item 1. # - List item 2. # @par # Numbered lists are available. # -# List item 1. # -# List item 2. # @par # Text may be @em emphasized. # @note This is a note included in the file section. # @see example-perl-executable.pl
## @class example_perl_module # The text here is a brief description of the class. # @par Paragraphs do not require headings. # There are no blank lines in this comment block. Following this text is a # detailed description of the class that may consist of multiple lines.
# @par # Additional paragraphs may be created. Note that \@par exists on its own line. use strict; our $VERSION = sprintf "%d.%d", q$Revision: $ =~ /(\d+)/g;
## @cmethod public new() # Template for a typical Perl object constructor. # @param param1 First parameter. # @param param2 Second parameter. # @return example_perl_module object reference. sub new { my ($class,%arg)=shift; my %args = validate(@_, { param1 => 1, param2 => 0, }); bless($self,$class); return $self;
PS1-MOPS Source Code Documentation 6 }
## @method public getSomevalue() # Template for a typical Perl accessor. # @return Some value. sub getSomevalue { my($self)=shift; # @note This is an arbitrary code note. # @todo This is a todo line. return $self->{_VALUE}; }
## @fn nonspecific_scope_function() # An example function without specified access scope. # @param param1 Parameter 1 description. # @param param2 Parameter 2 description. # @return 1 for true, 0 for false. sub nonspecific_scope_function { my (%arg)=@_; return 1; }
## @fn private _example_private_function1() # An example private function. # @param param1 Parameter 1 description. # @return 1 for success, 0 for failure. # @see example_public_method1(), example-perl-executable.pl sub _example_private_function1 { my ($param1)=@_; return 1; }
# This example includes a return value after the scope declaration. # By default, Doxygen doesn't include return values in the documentation unless # they are specified.
## @method public void example_public_method1() # An example public method. # @param param1 Parameter 1 description. # @return Void. sub example_public_method1 { my ($self,%arg)=@_; }
## @method protected example_protected_method() # An example protected method. # @param param1 Parameter 1 description. sub example_protected_method1 { my ($self,%arg)=@_; }
1; __END__
PS1-MOPS Source Code Documentation 7 Doxygen HTML documentation output for example Perl module
PS1-MOPS Source Code Documentation 8
PS1-MOPS Source Code Documentation 9
File example-perl-executable.pl The following code lists an example Perl module containing embedded documentation along with Doxygen filter commands. #!/usr/bin/perl -w
##@file example-perl-executable.pl # A Perl executable containing examples for Doxygen documentation. # @par DESCRIPTION # This is an example Perl executable containing source code documentation to # be parsed by a Doxygen filter. Multiple lines may be present, but the first # sentence or phrase, after the filename, is considered to be the brief # description for the file. # @par SYNOPSIS # Inserting a CR/linefeed is demonstrated here. # Run by calling\n # \$ ./example-perl-executable.pl use strict; our $VERSION = sprintf "%d.%d", q$Revision: $ =~ /(\d+)/g;
PS1-MOPS Source Code Documentation 10 main();
## @fn main() # An example main function for a Perl executable. sub main { # Function takes no arguments. }
## @fn nonspecific_scope_function() # An example function without specified access scope. # @param param1 First parameter. # @return 1 for true, 0 for false. sub nonspecific_scope_function { my($param1)=@_; return 1; } __END__
PS1-MOPS Source Code Documentation 11 Doxygen HTML documentation output for example Perl executable
1 Doxygen 1.3.9.1 is the version of the software used during the creation of this document. 2 Doxygen Filter 1.01 is the filter used to process Perl files using Doxygen. It was obtained from http://www.bigsister.ch/doxygenfilter/ 3 The formatting is dependent upon the type of revision numbers in use.
PS1-MOPS Source Code Documentation 12