On 8/23/04, [EMAIL PROTECTED] (Rod Adams) wrote:
>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...).
=)
>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 #etc....
Yeah, I was thinking of something like that. And it's not even uncommon
to have comments explaining what variables are for, only this way you'd
get something structured instead of just:
Foo::Bar $bar, # what to foo up
And that means you could do things like... I dunno what it would look
like, but... "pdoc Freudian::Slip" to display the usual manpage stuff,
or "pdoc --usage Freudian::Slip" to get a certain section, or "pdoc
Freudian::Slip &foo" to display just the info from a particular sub
(class/method/variable/etc.).
And then if POD(??) had some sort of "=lookup &foo" directive, you could
have a particular piece of documentation displayed somewhere other than
where the code & docs themselves are.
- David "that seems simpler than I expected" Green
