Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Re^2: Doxygen Perl Filter on Windows

by BAJA (Novice)
on Dec 27, 2011 at 23:46 UTC ( [id://945254]=note: print w/replies, xml ) Need Help??


in reply to Re: Doxygen Perl Filter on Windows
in thread Doxygen Perl Filter on Windows

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"; }

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 #*/

Or

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

Or

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

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 #*/

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

I look forward for your comments. Thanks again.

Replies are listed 'Best First'.
Re^3: Doxygen Perl Filter on Windows
by GrandFather (Saint) on Dec 28, 2011 at 09:23 UTC

    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

      There is no need to do the piping to a .cpp file and there is no need to write a wrapper that will parse a directory tree, it already does that. The Doxyfile configuration file controls all of that. You do NOT need to run doxygen-filter-perl as a stand alone script. Doxygen will call it as it parses the directory tree. All of this is standard doxygen style stuff. See the Doxygen manual for more information.

      As the docs on CPAN state, all you need to do is place a Doxyfile configuration file is the base of your project and then run "doxygen Doxyfile". You will then magically get a documentation tree called something like ./doc/html/

      I think you are trying to make this much harder than it is. I also think you are trying to use this like "perldoc" for viewing POD. Doxygen::Filter::Perl does not work by itself. You must have Doxygen installed and you must use Doxygen to call it.

        That would all be fine if it works as trivially as you suggest. However the OP and I both had the same experience trying to use the tool as described in the module's documentation. I had Doxygen installed. I followed the instructions in the POD (to the extent I could - see below). A doc folder was created where I expected it to be and there was an index.html file where I expected it to be. When I opened the index.html the page shown was essentially empty. By following the manual steps I described I could get Doxygen to generate the documentation I expected.

        There is a gap between the process you describe and what the OP and I experienced. Maybe there is a configuration setting somewhere that we have missed, but if so it is not clearly documented and you haven't mentioned it. I searched the Doxyfile for any Perl related configuration information that may be pertinent, but didn't find anything. Note though that there was no Doxyfile installed to the bin folder containing the doxygen-filter-perl script or in the Doxygen::Filter::Perl context, which were the only places I could think of to look in response to the "Copy over the Doxyfile file from this project" instruction.

        It would help a great deal if there were documentation for any special content in the Doxyfile that is pertinent to using Doxygen::Filter::Perl. It would probably also help if "this project" were rather less vague as on reflection this is most likely where things have gone pear shaped!

        True laziness is hard work
Re^3: Doxygen Perl Filter on Windows
by Anonymous Monk on Dec 28, 2011 at 23:18 UTC

    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

      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
Re^3: Doxygen Perl Filter on Windows
by Anonymous Monk on Dec 28, 2011 at 20:25 UTC

    Is it working for you now?

Re^3: Doxygen Perl Filter on Windows
by Anonymous Monk on Dec 28, 2011 at 06:30 UTC

    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;
    }
    

      Oh and another thing I just verified, the Doxygen::Filter::Perl.pm file is all documented with doxygen style syntax and POD so you can see how you can use both at the same time by just looking at the source

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://945254]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others studying the Monastery: (7)
As of 2024-03-28 19:47 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found