Darren Duncan asked:
> But one thing I'm not sure whether or not it was addressed is regards to
> whether free-form documentation is still supported or can be effectively
> combined with embedding documentation into the places that it is
> documenting.
Yes and yes.
Normal Pod blocks weren't mentioned in the executive summary because
they haven't changed. Except that they got much better, because now you
can indent them to match the layout of the code they're interleaving.
Or, indeed, indent them simply to indicate the Pod's own lexical
structure.
The Necrotelecomnicon example was originally written like so
(before I removed the Pod blocks...to keep the example properly
focussed):
=head2 IPC magic
=para
The base class for doing deep and dangerous things with IPC
is....
#= Base class for comms necromancy hierarchy
class Magic::Necrotelecomnicon {
has $.elemental; #= Source of all power
has $!true_name; # Source of all self-protection (not documented)
method cast(Spell $s)
#= Initiate a specified spell normally
{
do_raw_magic($s);
}
#= Initiate a specified spell abnormally
method kast(Spell $s) {
do_raw_magic($s, :alternative);
}
}
which, by default (and in the absence of any semi-literate or
OO-bsessive modules one might explicitly C<DOC use>),
will simply produce something like:
IPC Magic
The base class for doing deep and dangerous things with
IPC is....
Name: Magic::Necrotelecomnicon:
Desc: Base class for comms necromancy hierarchy
Attrs:
.elemental : Source of all power
Methods:
.cast(Spell $s) : Initiate a specified spell normally
.kast(Spell $s) : Initiate a specified spell abnormally
Damian
