Re^3: Doxygen Perl Filter on Windows

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

Comment on Re^3: Doxygen Perl Filter on Windows

Replies are listed 'Best First'.
Re^4: Doxygen Perl Filter on Windows by GrandFather (Saint) on Dec 28, 2011 at 23:46 UTC
This makes sense, however the people who have been bitten all seem to have been Windows users and we are accustomed to using tools such as Active State's ppm to install modules. We don't see the tar ball at all and, as far as I can see, there is no Doxyfile to copy. I suspect that many people who use cpan from a *nix command prompt may have the same issue because, again, there is no visible tar ball and no direct interaction with the unpacking process. A better place for a template Doxyfile would be in the site/lib/Doxygen/Filter/Perl folder alongside the POD.pm file or perhaps in the parent folder alongside the Perl.pm file. In any case the current documentation doesn't make it at all clear where the template file should be, nor how a default Doxyfile should be altered to enable the Perl filter. True laziness is hard work	[reply]

Replies are listed 'Best First'.

Re^4: Doxygen Perl Filter on Windows
by GrandFather (Saint) on Dec 28, 2011 at 23:46 UTC

This makes sense, however the people who have been bitten all seem to have been Windows users and we are accustomed to using tools such as Active State's ppm to install modules. We don't see the tar ball at all and, as far as I can see, there is no Doxyfile to copy. I suspect that many people who use cpan from a *nix command prompt may have the same issue because, again, there is no visible tar ball and no direct interaction with the unpacking process.

A better place for a template Doxyfile would be in the site/lib/Doxygen/Filter/Perl folder alongside the POD.pm file or perhaps in the parent folder alongside the Perl.pm file. In any case the current documentation doesn't make it at all clear where the template file should be, nor how a default Doxyfile should be altered to enable the Perl filter.

True laziness is hard work

[reply]