How to use Doxygen and Doxygen::Filter::Perl to generate documentation for Perl sub routines?

Question

I am trying to figure out how to use Doxygen::Filter::Perl to generate documentation for Perl files. I am starting with a very simple file just to see if I can get it to work (test_doxygen.pl):

#! /usr/bin/env perl
#** @file test_doxygen.pl
#  @brief  Testing Doxygen using Doxygen::Filter::Perl
#
# Description of the purpose of this file
#
#  @author Håkon Hægland (hakon.hagland@gmail.com)
#
#  @bug No known bugs.
#
#*

#** @class main
# The main class
#*

use strict;
use warnings;

my $b = add_one(1);

#** @function public add_one ($par1)
# @brief A brief description of the function
#
# A detailed description of the function
# @params $par1   required  A number
# @retval value   Input value plus one1
#*
sub add_one {
    my ($par1) = @_;

    return $par1 + 1;
}

I then installed Doxygen::Filter::Perl and used the Doxyfile configuration file provided by the package maintainer at metacpan.org (the link is here) and put it in the same directory as the script above. I changed one line in the Doxyfile: the value of the INPUT tag was changed from lib to the empty string, in order to only search the current directory for source files..

I am using Ubuntu 14.04, so I installed Doxygen with sudo apt-get install doxygen, (I also needed to install graphviz: sudo apt-get install graphviz) then I finally run

$ doxygen

from the terminal window. The generated HTML file doc/html/index.html contains documentation about the file and the author, but it does not contain any documentation for the add_one sub routine.

What am I missing here?

Update

Here is how the class view looks like in Chromium browser:

enter image description here

As seen, there is no reference/link to the add_one sub routine.

And here is the file view:

enter image description here

You are missing the idea that Perl Progammers use [pod](https://metacpan.org/pod/perlpod)? — mob, Mar 13 '15 at 13:50
@mob After reading this http://stackoverflow.com/questions/4722619/is-there-really-no-better-way-to-document-perl-code-than-pod I decided to try Doxygen :) — Håkon Hægland, Mar 13 '15 at 13:54

score 6 · Accepted Answer · answered Mar 17 '15 at 20:18

6

So the problem was with handling the "my" variable declaration. It set the value to be private: and doxygen never went back. I have added a line to Perl.pm to fix this and it should work for you now. Since you are working with pl files not pm files, I have also made changes to the Doxyfile, so you will want to get the new one from the distribution. I have published 1.71 to Github and CPAN and have tested it with your exact example.

answered Mar 17 '15 at 20:18

jordan2175

878
2
10
20

1

Thanks Jordan. It is working now! It looks great, thanks for your time. – Håkon Hægland Mar 18 '15 at 06:35

score 3 · Answer 2 · answered Mar 16 '15 at 21:21

3

I just posted a new version of Doxygen::Filter::Perl to Github and CPAN, version 1.70. This should fix the problems you were seeing.

answered Mar 16 '15 at 21:21

jordan2175

878
2
10
20

Thanks @jordan2175. But it still does not work. I ran `cpanm Doxygen::Filter::Perl` to update to version 1.70. Then rerun `doxygen` command, but I still get the same result. No `add_one` subroutine in either class view or file view in the browser.. – Håkon Hægland Mar 17 '15 at 06:43

score 2 · Answer 3 · answered Mar 13 '15 at 22:58

2

I just looked at this and it seems to work with Doxygen (1.7.5.1), however, the newer version of Doxygen (1.8.9.1) does not seem to work well.

answered Mar 13 '15 at 22:58

jordan2175

878
2
10
20

Thanks @jordan2175. I am using version 1.8.6. – Håkon Hægland Mar 14 '15 at 08:16

How to use Doxygen and Doxygen::Filter::Perl to generate documentation for Perl sub routines?

3 Answers3

Linked