If the two can be made eqaully expressive (i.e. content is normal POD, and multiple lines merged logically), I think I favor the pod-comment form, since it allows one to place the doc close to the thing documented - in particular, to the head of the function definition. That's a convenience for the user puzzling out the signature, and a reminder to the author to update the doc when the signature changes.
On 5/3/09, Damian Conway <dam...@conway.org> wrote: > 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 > -- Regards, Charles Bailey Lists: bailey _dot_ charles _at_ gmail _dot_ com Other: bailey _at_ newman _dot_ upenn _dot_ edu