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.