Hi all,
The observations got a little long, so I'll put the questions first.
1. Do you want to be able to interlace your ACTION_foo pod?
2. Would you want to be able to use =head2 rather than =item for it?
3. Does you document your build subclass?
3a. Where did you find the M::B documentation for how to do that?
4. Why doesn't get_action_docs use M::B::PodParser?
And now back to the regularly scheduled observations...
I'm looking at how Module::Build expects your help to be formatted for
individual actions, e.g.
./Build help foo
In general, there is an /^=head1 ACTIONS\b/ section which must contain
the /^=item $action\b/ item for the action in question.
Currently, this mostly assumes that you use the "pod after __END__"
convention, or otherwise lump all of the pod together. Since the build
class for dotReader was at 1600 lines, I was finding this somewhat
difficult to maintain, not to mention keeping track of whether each
action had been documented.
I like my pod interlaced.
Now, "=item foo" is fine for this -- that's valid pod if you keep track
of the =back and put some =cut lines in there.
=head1 ACTIONS
=over
=cut
# blahblahblah
=item foo
=cut
sub ACTION_foo { ...}
# various other actions
=back
=cut
# all supporting (non ACTION_*) code has to be down here
Ok, but now ./Build help foo prints the source for the foo subroutine!
(And actually, all of the source until it sees another /^=(item|
back)/.) That's a little more help than I wanted.
This can be made to work by simply adding =cut into the stop condition.
However, =item entries do not show up in the index at the top of most
htmlized pod (and one could rightly argue that they shouldn't.)
I would like to use =head2, which fits my typical documentation style,
and gives a linkable index like:
Methods that do X
method
another_method
Methods that do Y
a_y_method
Or, more specifically:
ACTIONS
code
test
testgui
testall
help
Of course, this is going to introduce some complication into how the
builtin "pod parser" handles finding your action docs. Also, it looks
like the test coverage is a bit light in that area, so pod samples
would be greatly appreciated.
Thanks,
Eric
--
Speak softly and carry a big carrot.
---------------------------------------------------
http://scratchcomputing.com
---------------------------------------------------
