Perl Documentation like Javadoc

[Viraj Purang]

I would like to generate methof/subroutine related documentation for a Perl
project that I have just finished.
What is the best way of doing it ? can you also specify which
commands/executables to use for this ?

Viraj B. Purang

[James Edward Gray II]

On Feb 10, 2004, at 2:51 PM, Viraj Purang wrote:

> I would like to generate methof/subroutine related documentation for a
> Perl
> project that I have just finished.
> What is the best way of doing it ? can you also specify which
> commands/executables to use for this ?

Perl's Javadoc-like cousin is called POD. You can read about it with
this command:

perldoc perlpod

James

[Wiggins D Anconia]

> On Feb 10, 2004, at 2:51 PM, Viraj Purang wrote:
>

> > I would like to generate methof/subroutine related documentation for a
> > Perl
> > project that I have just finished.
> > What is the best way of doing it ? can you also specify which
> > commands/executables to use for this ?

>
> Perl's Javadoc-like cousin is called POD. You can read about it with
> this command:
>
> perldoc perlpod
>
> James

You may also be interested in OODoc, haven't used it personally, but
Mail::Box is a pretty impressive example of it:

[url]http://search.cpan.org/~markov/OODoc-0.10/lib/OODoc.pod[/url]

Conveniently written by the guy that leads Mail::Box development.

[url]http://danconia.org[/url]

[Richard Heintze]

Speaking of documentaiton, is there any structured
approach to documenting the get/post parameters for a
perl web page?

I have a main menu type of of page I have inherited.
The GUI designer is not a programmer seems to have a
strong preference buttons instead of links or drop
down menus.

Each push button represents another target page which
has its own set of get/post parameters which require
its own, sometimes conflicting, hidden HTML fields.
The code is SOOOOO ugly because the previous
programmers had no naming conventions and did not
understand SQL.

Is there any structured approach to say:

These hidden variables are for these destinatino
pages. These are the get/post parameters for this
page, etc...?

and
Here are the get/post params this page needs?

Javadoc won't even help me with this (if I was using
Java).

Siegfried

__________________________________
Do you Yahoo!?
Yahoo! Finance: Get your refund fast by filing online.
[url]http://taxes.yahoo.com/filing.html[/url]

[R. Joseph Newton]

Richard Heintze wrote:

> Speaking of documentaiton, is there any structured
> approach to documenting the get/post parameters for a
> perl web page?
>
> I have a main menu type of of page I have inherited.
> The GUI designer is not a programmer

That is as it should be. GUI design should be focused on offering a natural
experience to
the user, and internal technical considerations should be secondary at that
level of abstraction.
That being said, multi-tier development projects do require clarity and the
interfaces between tiers.

> seems to have a
> strong preference buttons instead of links or drop
> down menus.

Can you explain what, in terms of information, is missing from the buttons that
would show up in the
links or menu items?

What kind of information is being gathered here? What is the overall purpose of
the system?

>
>
> Each push button represents another target page which
> has its own set of get/post parameters which require
> its own, sometimes conflicting, hidden HTML fields.
> The code is SOOOOO ugly because the previous
> programmers had no naming conventions and did not
> understand SQL.

The question I see at this point is:
What is the scope of the project? Are you doing a restructure of the system as
a whole?

If so, then I would suggest starting out by developing a Data Dictionary for the
overall system.
By doing this, you can ensure from the start that there is a common protocol and
a common set of
identifiers meaning the same thing throughout the system.

>
>
> Is there any structured approach to say:
>
> These hidden variables are for these destinatino
> pages. These are the get/post parameters for this
> page, etc...?
>
> and
> Here are the get/post params this page needs?

This sounds like a question of system design.
There are indeed a number of tools and conventions available to use in defining
or describing
a project and the role of each element in the context of the system as a whole.
Unfortunately,
you are not sharing the kind of detail that would help us steer you in the right
direction for your
needs. You seem more to be venting frustration--very understandable, but not
immediately
constructive.

For what it's worth, Perl will function very well in handling CGI form input, no
matter how bad
the naming convention in the HTML may be. A string is just a string, to Perl.
If you are not
ready to, or in a position to, do a global restructure, I would advise doing a
data dictionary for
your own use, possibly with a table correlating the name and value strings of
the HTML with
the internal names of corresponding variables in your CGI layer. Although it
can certainly be
convenient to have the strings correspond across all layers of your system, it
is by no means
mandatory. You may have to just work with what you have.

>
>
> Javadoc won't even help me with this (if I was using
> Java).
>
> Siegfried

Something you should understand about multi-tier systems--a large degree of
independence
between the layers is part of the plan. There should be clearly defined
interfaces between
the layers, definitely. Still, the internal structure of each layer should be
focused on the needs
of that layer. Tight coupling between the layers in a multitier processing
system is likely to
hobble each in performance of its work

Joseph