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
