Hinrik Örn Sigurðsson wrote:
> 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].
For the latest S26 proposal that I'm (very quietly) working on, I'm
considering two possible mechanisms to support tying docs to specific
components of a program.
The first is an C<is doc> trait:
method reverse (
Bool $recursive is doc<Reverse any nested L<List>s too>
)
is doc<Returns a copy of the L<List> with the order of elements reversed.>
{
my @result;
for @.list {
@result.unshift($_);
}
return @result;
}
The second is a generalized Pod comment form:
method reverse #={ Returns copy of L<List> with order of elems reversed. }
(
Bool $recursive #={ reverse nested L<List>s too }
)
{
my @result;
for @.list {
@result.unshift($_);
}
return @result;
}
Each approach has advantages and disadvantages.
Feedback via this forum would be most welcome.
> Something similar could be done for MODULE, CLASS, GRAMMAR, ROLE,
> TOKEN, and REGEX.
Indeed. And with both of the above alternatives that's also true.
> One advantage to using Pod blocks in place of actual strings a la
> Python, is that the documentation is still independent of the source
> code, and need not be in the same file.
That's certainly true of your proposal. However, many might argue that
one *disadvantage* of using Pod blocks plus :name<> that way is that the
documentation is independent of the source code, and need not be in the
same file. ;-)
Damian
