How about you give us an example of what you mean by "I cannot manage to make it work". Have you a small sample script that you have tried as a test case and can tell us how it failed?

Another way for you try this, and the way I figured it out for my own projects, which it works super well for. Download the tar ball from Sourceforge and decompress it. Then do the "perl Makefile.PL", "make", "make install". And then from that same directory, you can run "doxygen Doxyfile". You will now see a docs/html/ directory. And you can open it in your web browser to see the output.

Using Doxygen::Filter::Perl is super easy to use and works really well. It even knows how to handle that POD stuff. I have been using it since RC1 was released and have sent the author several bugs and enhancement requests, and he was super responsive.

I will say that you are right in that this is a confusing mess and the directions were not at all clear to me as a non-Doxygen user! I don't think the problem is Windows...it is the limitations and capabilities of the Perl-filter?

Let's back up a bit...You are asking about Doxygen, but what you want is listing of function/method/subroutine(s) in a bunch of Perl modules which don't already have any documentation about these things.

I'm not sure that Doxygen will do what you want. Maybe there is another way to do it? I am hoping some other Monks can enlighten us. Perl is an amazingly introspective language and there may be a way to do what you want in a different way.

I ran doxygen-filter-perl on a simple .pl file. It looks like the goal of this thing is to produce "C/C++" pseudo statements that the Doxygen engine can then parse. I didn't install the complete (and apparently separate Doxygen program).

There is some guess-work here, but it looks like in the best case this thing will run your code and log the functions it calls? That's a different question than what are all of the functions in the source code (may be more than are called).

I have my doubts that this thing or anything for that matter can produce something as clear as a well written C declaration from Perl code - and even that might not be all that clear if all you have are the types and names.

I mean you may have to get down to having to manually write text in the form of comments about what each function does, expects and returns. Entropy is working in the wrong direction here. Perl - especially poorly written Perl - can be very cryptic even to a human versed in the art.

Example: "use" becomes "#include":

C:\TEMP>doxygen-filter-perl wxdata.pl
/** @file wxdata.pl
@version 1.00
*/
#include "HTTP/Request/Common.pm"
#include "LWP/UserAgent.pm"
#include "constant.pm"
#include "constant.pm"
#include "constant.pm"
[download]

Hi GrandFather and Marshall,

First thank you for your reply.

Well Marshall, I agreed with you, Perl is not that structured as C/C++ or similar languages, Perl gives too much freedom to the programmer on how things can be done.

GrandFather, is difficult to tell where it fails because I don't get any errors, all the files that Doxygen generates are there, but when opening the only thing listed is the file that contains the subroutines. Errors I've got where normal from Doxygen that I could solve.

I'm not looking or expecting that Doxygen and the filter do all the work. I know I have to comment most of the files and edit some other things to get the results I want. So, I'm sorry if what I wrote seemed like I was looking for someone to do my work. It was not my intention I'm still learning english. :-D

The example I have is as follows:

sub marine {
  $n += 1;  # Global variable $n
  print "Hello, sailor number $n!\n";
}
sub printcelsius {
  $degc = ($degf - 32) * (5/9);
  print "$degf degrees fahrenheit is $degc degrees celsius\n";
}
[download]

Now, imagine around two to four thousand of subroutines like these on which I have put all the comments I list below.

These are my tries:

1) "Using" Doxygen syntax

#/** \fn int mult (int x, int y)
#\brief Multiply two number.
#\param x Factor 1.
#\param y Factor 2.
#\retval Multiplication
#*/
[download]

Or

#** \fn int mult (int x, int y)
#brief Multiply two number.
#param x Factor 1.
#param y Factor 2.
#retval Multiplication
#*
[download]

Or

## \fn int mult (int x, int y)
#brief Multiply two number.
#param x Factor 1.
#param y Factor 2.
#retval Multiplication
[download]

1) "Using" Perl-Filter syntax

#/** @method public int mult (int x, int y)
# @brief Multiply two number.
# @param x Factor 1.
# @param y Factor 2.
# @retval Multiplication
#*/
[download]

I have used them before, after and inside the subroutines without any luck yet.

I look forward for your comments. Thanks again.

Sorry, I didn't intend to imply you wanted us to do your work for you, but just that I couldn't figure out from your description what problem you were having. In such cases examples can help a lot.

I got curious about the problem and it turns out that the module documentation is crap! Marshall had part of the answer and careful trawling through the module documentation and a little experimenting provided the rest. The key is that doxygen-filter-perl, as the name suggests, is just a filter. Use it as: doxygen-filter-perl source-file.pm > source-file.cpp then use doxygen Doxyfile as suggested in the documentation to parse the .cpp files and generate the documentation.

If I had a pile of this stuff to do I'd write a wrapper script that processes a directory tree of modules and scripts to do the doxygen-filter-perl step (copy appropriate code from the doxygen-filter-perl script).

True laziness is hard work

I was pointed to this thread by a user. And after reading the various posts, I am beginning to see the disconnect. Yes the POD docs on CPAN make an assumption that a user has used Doxygen before and is familiar with Doxygen setup and configuration. So let me explain a bit to clarify.

Doxygen needs a configuration file to tell it what to do. This configuration file is setup to be per project/per script. Most of the time Doxygen is used to document a project not a single script. The configuration file is called "Doxyfile" by default. This configuration file tells Doxygen to look in a directory called "./lib" to find the various .pm files to document. If you want to look else where or look at a specific file, you need to change the Doxyfile configuration file (this is all documented in the Doxygen manual and I suggest using the Doxywizard tool to make the changes). Think of this in the context of development of a perl module. You have a directory that looks like: ./projectname/lib/something.pm and any other .pm files will be in this tree somewhere.

Now the doxygen-filter-perl script is called by Doxygen via the Doxyfile configuration. And it will go down the entire './lib' directory from where it is located and find every .pl and .pm and produce documentation for it. This doxygen-filter-perl is defined in the Doxyfile configuration.

Now Doxygen is a bit of an animal to configure and is not for the faint of heart. This is why I ate my own dog food and documented Doxygen::Filter::Perl with doxygen style syntax and included a Doxyfile in the distribution to help people get started. This file should be in the root of the tar ball. So if you untar the latest 1.00 release you will see the README, the Makefile.PL, the MANIFEST, and you will also see a Doxyfile configuration file. Copy this Doxyfile out of the project and stick it at the base of your project. You will need to edit it like the CPAN doc states to change the name and version. You will also want to change the "./lib" configuration if you are using some other directory tree structure or maybe change it to just "./" to look at the current directory level. Once you have a copy of my Doxyfile edited for your project in your root directory of your project, you can simply run "doxygen Doxyfile" from that directory.

Please let me know if I need to provide more details than that. Also, please feel free to contact me via SourceForge or the discussion board on SourceForge

Bret

Have you tried looking at the documentation on CPAN for this? http://search.cpan.org/~jordan/Doxygen-Filter-Perl-1.00/lib/Doxygen/Filter/Perl.pm Have you asked this question on the Doxygen::Filter::Perl discussions board on SF?

There are few things you need to do to make this work.

• You need to have Doxygen installed on your computer. And you need to have the doxygen command in your path. I am guessing in Windows land this would be doxygen.exe
• You need a Doxyfile configuration file for your project or script. This basically tells Doxygen what to do, where to find files, and where to put the html output. I would suggest using the Doxyfile example that is included in Doxygen::Filter::Perl. The CPAN docs explain the two options that needs to be changed.
• There is a perl script called doxygen-filter-perl not to be confused with Doxygen::Filter::Perl that Doxygen will call to figure out which files to pre-filter. This script will look for files with a .pl or .pm. You can changes this how ever you need. On Windows you will also probably need to make sure the Doxyfile configuration file points to where ever you have doxygen-filter-perl installed.

Then all you need to do is run "doxygen.exe Doxyfile" and it will generate some html output for you. The CPAN docs say that what this does is generate C like documentation out of the perl code/model so that doxygen can understand it. Thus a "use" command is turned in to a #include. This will make all of the inheritance diagrams work right and do some pretty cool things for documenting your perl code.

As far as documenting a subroutine, once again, look at the Docs on CPAN.

#** @function public subnamedfoo ($var, $foo, $bar)
# This function subnamedfoo does XYZ
# and it does some more of this and that
# @params var required this value is for xyz
# @params foo required this value is for abc
# @params bar optional this is not really needed for xyz
# @retval retval this is a string that does bla
#*
sub subnamedfoo {
my $var = shift;
my $foo = shift;
my $bar = shift;
#..... do something ......
return $retval;
}

Is it working for you now?

Hello everyone again.

Ok, first, I don't like fights at all, everyone has its own opinion and can give its own advices, so the person that asked for help chose the one he wants and understand, it does not matter if it is difficult or not, efficient or inefficient, slow or faster. The person that asked for help would know its needs and will choose the method that better suits its problem.

The main objective is to share information, not to point out what is good and what is bad as if there was only one way to solve something. Point out PROs and CONs, I think is a better approach.

In any case, I really appreciate all the comments in this thread.

Put all previous aside, let me clarify some things:

1- I have used Doxygen before, since I could reproduce some old C++ projects I did in the past under a Linux environment. So, I have a little experience using Doxygen, but I cannot say I'm expert or that is easy or me to use it or configure it, since I mostly used the defaults with some little tweaks. But I do know I need to install the program and need an executable on Windows. I don't know what happened, but I thought I mentioned in my first comment, what makes me think that there is a long way to walk before I can express myself correctly. :-)

2- I forgot to add the original Perl-Filter syntax when I listed the syntax variations I used:

#** @method public int mult (int x, int y)
# @brief Multiply two number.
# @param x Factor 1.
# @param y Factor 2.
# @retval Multiplication
#*
[download]

And not even like this I couldn't manage it to work.

GrandFather, I do get the doxyfile from the .tar.gz file, I used 7zip program to "untarted" and "unhizipped" or simply extract the files twice to have Doxygen-Filter-Perl directory. You'll find the doxyfile in Doxygen-Filter-Perl directory, the same directory where you use perl MakeFile.pl, nmake test and nmake install. I wrote nmake because I have Visual C++ compiler.

Now, doxygen Doxyfile did not work for my project using the commenting variations I mentioned. But, after reading a anonymous comment, I started playing with Perl.pm, and wonderful!! the filter worked with the doxyfile in the tar.gz and some minor changes in the doxyfile as Bret pointed out (I did those changes since the beginning of this thread).

Because Perl.PM is similar to the Perl files I need to create a documentation from, I took out some lines that my files don't have:

use 5.8.8;
use strict;
use warnings;
use parent qw(Doxygen::Filter);
use Log::Log4perl;
use Pod::POM;
use Doxygen::Filter::Perl::POD;
[download]

and now the all the generated documentation does not work, the only thing that got generated was the description of the file, there is no documentation for the subroutines.

So, my question, does this means that the only way Filter-Perl work is if a have I package statement?

As GrandFather asked me for a test case, well, now I have something more tangible:

With Doxygen installed, in the following path you can see an example of what I want to accomplish:

C:\Program Files\doxygen\examples\structcmd

to which I want to add the feature of the documentation of Perl.pm generated with Filter-Perl. That is the possibility of seeing the code of a subroutine with a click on "View code" link.

As always, I'll looking forward for comments.

Thanks.

Baja,

I would like to understand what does not work for you so that I can either fix it in code or fix the documentation. Since I do not run windows, I am linux and Mac OSX, I can not try this myself. But I would like you to try this for me:

1) You have doxygen installed and doxygen.exe is in your path.

2) Download Doxygen-Filter-Perl-1.00.tar.gz to c:\temp\ from http://sourceforge.net/projects/perldoxygen/files/

3) Extract Doxygen-Filter-Perl-1.00.tar.gz to c:\temp\Doxygen-Filter-Perl-1.00\ with your 7zip or the tar/gzip tools for windows from http://unxutils.sourceforge.net/

4) cd to c:\temp\Doxygen-Filter-Perl-1.00\

5) So while you are in this directory edit the Doxyfile to change the location of the doxygen-filter-perl script to where ever you have it, or to use the one in c:\temp\Doxygen-Filter-Perl-1.00\bin\

6) From c:\temp\Doxygen-Filter-Perl-1.00\ run "doxygen.exe Doxyfile" This should create a directory called doc\html\ here: c:\temp\Doxygen-Filter-Perl-1.00\doc\html\ Now inside the html directory there will be an index.html. You should be able to open that and see the output of using Doxygen::Filter::Perl against itself. Thus see the internal documentation for Doxygen::Filter::Perl.

Please let me know if that works for you. If that does, then we can start looking at why this does not work for your .pl file.

Bret

Hello everyone,

I'm back with good news. In this period without any news I've worked with Bret (the current maintainer of this filter) and he find out what the problem was in the filter's source code, so now he released a new version (1.01) that can be found here:

• Doxygen-Filter-Perl-1.01

Thanks to everyone that tried to help and left its comments or opinion.

Hi everyone,

Thanks for all your replies, I've already read all your post. I'll be trying your suggestions, so I hope I'll be posting m comments tomorrow morning.

Sorry for the late response.

Thanks again.