* Damian Conway (dam...@conway.org) [090504 00:03]: > 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].
We had long and fierse fights about it, back in July 2007. Challenged by Damian, I can up with http://www.nntp.perl.org/group/perl.perl6.language/2007/07/msg27894.html And never heard from it since. (I know you are busy) > 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.> > > 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 } > ) Does this mean that it now will be acceptable to interlink documentation with information from the code? I would certainly appreciate that change. > > 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. ;-) The "=begin METHOD" is the starter of the method implementation (docs are as important to programs as code is), so is a big advantage to read the documented subject on the initial line. Certainly if the documentation gets longer. However, for my taste, the focus is attracted to the wrong components of the line. I would prefer =begin METHOD :name<reverse> =method reverse Acts on a L<List>. Returns a copy Acts on a LIST. Returns a copy =end METHOD =cut method reverse() { method reverse() { (=end METHOD suggests that the method ends there, but of course, the coding part still has to come. That's confusion) Or, simpler (alternative syntaxes) method reverse() { method reverse() { #= Acts on a LIST ` Acts on a LIST. #= Returns a copy ` Returns a copy. Documentation and comments are alike: Documentation for external module users, Comments for internal module users. Therefore, I think that a '#= ' comes naturally next to the '# ' I suggest a syntax abbreviation from m/^\s*\`/ to "is doc<>" -- MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
