David Green skribis 2004-08-23 11:30 (-0600):
> One of the selling features (or one of the features that is always sold)
> of POD is that you can mix it with your code. Except nobody does, at
> least I can't recall that last time I saw a module that did that, and I
> don't think I've ever really done that myself. The POD usually sits in
> a lump at the end of the file.
I'll consider inline documentation when POD can be inlined. But as long
as =command paragraphs need to start in the first column, I'm not
interested in this feature.
> Having a nice, compact way to declare sub signatures is good. Being
> able to document those signatures, not just "nearby", but
> *simultaneously*, would be great.
IMHO, with Perl 6's verbose signatures, it'd really help if POD could
copy the signature literally. This is one small thing I do like about
PHP documentation.
I also think POD should be overhauled completely. I've been thinking
about proposing something like:
sub foo (
Foo::Bar $bar,
Quux::Xyzzy $xyzzy,
+$verbose,
+$foo
) description {
Calculates the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
} returns Array | undef {
# real code here
}
which would get rendered as:
&foo (Foo::Bar $bar, Quux::Xyzzy $xyzzy, +$verbose, +$foo)
returns Array | undef;
Calculate the foo-intersection of $bar and $xyzzy, optionally
blah blah blah...
Having {} instead of <> would also please me. Especially if we can get
{b:foo} instead of B<foo>.
But I haven't really given this much thought. That's why I haven't
proposed it yet. But since POD is a hot topic now anyway, let's see what
everyone thinks about this.
Juerd
