David Green wrote:
(Unless I'm missing something, which is always possible; you can put
a piece of POD geographically next to a Perl declaration, but I'm not
sure that's unambiguous enough. Hm, why not? POD doesn't know
what's going on around it, but Perl does, and could say, "I've just
declared $size, and the next line starts a chunk of POD, so I'll
simply copy it into $size's 'documented' trait... would that work??)
It is doable: say that any Pod section that appears within or after a
class definition is considered by perldoc to refer to that class.
The problem with this is that you're forcing the Pod author to
organize his documentation in a manner that precisely mirrors the
organization used by the Perl programmer, and to scatter it throughout
the module. This isn't necessarily a deal-breaker because the Pod
author is usually(?) going to _be_ the Perl programmer (thus letting
him reorganize the classes to match the preferred documentation
sequence or vice versa), and because the Pod author may _prefer_ to
place the documentation in close proximity to the source code being
documented. But it would be nice to have more freedom of placement of
documentation for those with other preferences.
There's the new 'A<>' tag, which specifically refers to a word or
phrase in the source code. But that's a single inline tag; so it's
questionable as to how useful it would be for the purpose of
associating an entire Pod section to a piece of source code. In
addition, the 'A<>' tag, as written, makes explicit use of exactly the
geographic positioning that we're trying to get around.
--
Then there's the suggestion that I made about providing a Pod rule (or
Pod rules) for the purpose of identifying points in or sections of the
source code for more robust referencing. In my proposal, I suggested
being able to say something like '=code Foo' to identify the start of
a section of source code that abstractly relates to the label 'Foo',
coupled with the ability to tell a Pod section elsewhere that it is
associated with the source code identified by 'Foo' (using something
like '=begin pod :A<Foo>' to do so).
At the time, I was thinking in terms of allowing more freedom of
placement of 'A<>' tags; but it also works for giving entire pod
sections freedom of placement while still maintaining ties to specific
source code: for example, perldoc could look for the '=code' rule that
precedes or encompasses a given class definition and then associate
any Pod sections that attach themselves to that rule with that class.
So while the '=code' rule would have to maintain a close geographic
relationship to the source code in question, the documentation itself
would not.
Ideally, this wouldn't replace the proximity-based bindings, but would
supplement it, with the idea that Pod sections with :A<...> traits
would be bound to whatever follows the associated '=code' rule, while
those without :A<...> traits would be bound to whatever they follow.
Best of all, none of these bindings would be Pod's responsibility. As
far as Pod is concerned, the only use that '=code' rules would have
would be in service to 'A<>' tags, and could maintain ignorance about
what the source code speaks of. Perldoc would have the final
responsibility of binding documentation to definitions.
--
The other way to go about it would be to have the source code refer to
Pod sections:
class Foo is documented(Bar) {
has $.x is documented(Baz);
}
...
=begin Bar
...
=begin Baz
...
This places the responsibility of bindings on the language (in this
case, Perl) - each of which would have to come up with its own syntax
for referencing documentation. This is fine as far as Perldoc is
concerned, but does raise issues if you decide that you want to do
something similar with, say, C++ or HTML.
--
Jonathan "Dataweaver" Lang
