On Wed, Jul 23, 2003 at 10:49:40PM -0600, Nick Pinckernell wrote:
> The idea is: a structured Javadoc style system for Perl. It would be very
> dependant on multiline comments (I've seen the Perl 6 RFC).
>
> I think this idea would be really good for Perl 6, because, in my opinion,
> POD is lacking.
Nick,
Are you designing something for Perl6, or Perl5? In what way do you
find Pod lacking?
If you'd rather write comments with some Javadoc like notation,
you're free to do so. Just remember that your Javadoc-like docs
won't integrate with the rest of the documented Perl code in use
today. And don't expect the rest of the Perl community to race to
convert hundreds of thousands of lines of Pod, either by hand or
by using an automated tool.
But whatever you do, don't call your new tool or format 'perldoc'.
The Perl community has used Pod and perldoc for about a decade now.
I doubt anyone is 100% happy with it, but we are all quite happy
with the results: lots of docs that are easy to read, and easy to
write. Yes, there are more optimal syntaxes to capture the
information and better syntaxes to support better formatting.
That's not the point. The point is to *encourage* people to *write*.
New formats are worse, even if they are better than Pod in some
abstract way, because they inhibit doc writing.
Keep in mind that Perl is a more complex language than Java. The things
Javadoc can do by parsing code just can't be done with Perl.
- Subs can be created at runtime, so parsing code does not
necessarily determine a module's true interface.
- Perl subs can be polymorphic, behaving differently in scalar/list
contexts or if they are called with named args or positional args.
This is another area where Javadoc can extract definitive information
but even Perl cannot.
Z.
