On Apr 14, 2007, at 4:17 PM, Eric Wilhelm wrote:
Three behavioral questions:
1. doc-only overrides
2. accumulation is a bug?
3. formatting
-----------
1. Should subclasses be able to override *just* docs?
e.g. =item help in the subclass documentation gets picked-up even
if the
method hasn't been overridden. This seems like it could cause trouble
if you override the action and docs, but then delete your ACTION_help
sub and forget to kill the docs.
Heh. Yeah, I suppose that would cause trouble, but so would doing
lots of weird things. =)
Yeah, maybe not worth it. At least, wherever it is that we're
documenting `./Build help` wrt subclassing (I can't seem to find it),
we should mention how this all works.
Yeah, like "we search for action docs via the @ISA hierarchy, just
like a search for a method" or something.
-----------
2. If documentation is found in a subclass and superclass, should
we be
concatenating them together? It really seems like we should just stop
when we find some doc.
I guess the answer depends on whether the author is writing their POD
primarily for someone to read in the pod doc, or for the 'help'
action. The main difficulty probably happens when someone overrides
a method to add a small piece of functionality to it, because then
their docs will probably just say "does the 'foo' action and also
does 'bar'". And the user still won't know what 'foo' does.
-----------
3. Formatting?
The [version foo] stuff in the core docs doesn't seem too useful on
the
command-line. Similarly, the =item should probably be stripped and
maybe convert the pod markup to plaintext (and maybe Term::ANSIScreen
highlighting?)
Is there some reasonable way (on reasonable platforms) to figure out
if the terminal is ANSI-color capable? I was looking at Term::Cap
and I almost went cross-eyed. It would be nice to have snazzy help
output, but we don't want to put chickenscratch all over someone's
screen if they're just trying to get help on something.
-Ken
