Juerd wrote:
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.
What if we add C<doc> attribute that the execution compiler would discard, but POD compilers (and debuggers) could make use of? I believe that would even allow a particularly stringent corporate policy to create a flavor of 'strict' which required documentation of various classes of elements (though whether anyone would work there is another question...).
But imagine debugging code, and being able to quickly see a comment on a variable you can't figure out.
Juerd's sample would become:
sub foo :doc("take an Foo::Bar, and foo it over.") (
Foo::Bar $bar :doc("what to foo up."),
Quux::Xyzzy $xyzzy :doc("Xyzzy to foo bar with"), +$verbose,
+$foo
} returns Array | undef {
# real code here
}
-- Rod Adams
