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