I've been thinking lately about how Perl 6 might offer functionality
similar to Python's docstrings. That is, documentation which is tied
directly to a particular routine, class or module[1]. This is
something which would is very useful in a REPL, and for documentation
readers[2].
Taking one case, the usual Perl 5 way to document methods is to put a
METHODS heading in the Pod and then list all the methods as
subheadings or list items underneath it. However, Synopsis 26 has this
notion of semantic blocks, and already defines some standard ones
including SYNOPSIS, so you can write something like this:
=begin SYNOPSIS
Bla bla
bla bla bla
=end SYNOPSIS
The formatter might then print out a "Synopsis" heading with the block
text beneath it, since the two are reliably tied together, while the
"=head1 SYNOPSIS + any number of paragraphs" combo doesn't tell the
formatter much about the structure.
Now, S26 also specifies METHOD and SUBROUTINE, but their use is not
discussed. As I understand, Perl 6 will give you access to all Pod
blocks through $=BLOCKNAME. I suppose there might be @=BLOCKNAME if
there's more than one block by that name. If so, then using semantic
blocks seems like a shoe-in for providing docstring-like
functionality. We could have something like this:
=begin METHOD :name<reverse>
Acts on a L<List>. Returns a copy with the order of the elements reversed.
=end METHOD
method reverse() {
my @result;
for @.list {
@result.unshift($_);
}
return @result;
}
Something similar could be done for MODULE, CLASS, GRAMMAR, ROLE,
TOKEN, and REGEX.
One advantage to using Pod blocks in place of actual strings á la
Python, is that the documentation is still independent of the source
code, and need not be in the same file.
1. http://www.python.org/dev/peps/pep-0257/
2. E.g. http://svn.pugscode.org/pugs/docs/u4x/README
