Re: Docstrings in Perl 6
* 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 Cis doc trait:
method reverse (
Bool $recursive is docReverse any nested LLists too
)
is docReturns a copy of the LList with the order of elements reversed.
The second is a generalized Pod comment form:
method reverse #={ Returns copy of LList with order of elems reversed. }
( Bool $recursive #={ reverse nested LLists 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 :namereverse=method reverse
Acts on a LList. 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 MScMARKOV Solutions
m...@overmeer.net soluti...@overmeer.net
http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Docstrings in Perl 6
These two (generalized Pod comments and Cis doc are both better than
my suggestion. :) They require less typing, so documenting at a finer
granularity (e.g. object attributes) is easier. It would provide an
opportunity for very thorough auto-generated documentation as outlined
in Mark's 2007 post
In Perl 5 I hate having Pod interleaved with code, since it is usually
mostly /user/ documentation and so just gets in the way. Having normal
Pod elsewhere (at end-of-file or in a different file) and keeping API
Pod docs inline (and having tools which might merge the two into nice
HTML if desired) would be the best of both world.
As for #={ Pod } vs is doc, since I've been working on Perl 6
highlighting in vim, the first difference that comes to mind is that
highlighting the #={ Pod } form like other Pod (with Links looking
distinct n' all) is easier and makes more sense since it's not just a
normal string (which might have come from anywhere). Highlighting the
other form would be a special case that might be hard to detect, and
arguably shouldn't be, since it is just a string.
Re: Docstrings in Perl 6
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 Cis doc trait:
method reverse (
Bool $recursive is docReverse any nested LLists too
)
is docReturns a copy of the LList 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 LList with order of elems
reversed. }
(
Bool $recursive #={ reverse nested LLists 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
Re: Docstrings in Perl 6
On Mon, May 4, 2009 at 12:30 PM, Charles Bailey
bailey.char...@gmail.com wrote:
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.
If the #={ } form (or #=, #=«», etc) works like embedded comments (
#{ } ), what you're describing would work just fine since they can
span multiple lines. See
http://perlcabal.org/syn/S02.html#Whitespace_and_Comments
Re: Docstrings in Perl 6
The only reason that Pod directives have to be at the beginning of the
line is so that Pod parsers don't need to know Perl (or any other
language) in order to extract Pod from files, right? Allowing them to
be indented like I suggested would break that, but the tool would need
to parse Perl in order to find the #={ } comments anyway, and to tie
them to surrounding Perl structures.
Re: Docstrings in Perl 6
I suppose that #={ } would work like a normal Pod block which does not
allow implicit code. That way you could keep it properly indented by
default:
class Foo;
method bar ($x, $y) {
#={Swaps $x and $y}
...
}
method baz ($a, @b) {
#={
Takes $a, applies it to the values in @b
Bla bla bla
}
...
}
I remember reading that #{} comments are not allowed at the beginning
of a line. Is that still true? Would that also apply to #={} ? If so,
it would be easy to make a mistake:
class Foo;
#={ This class does something neat } -- ILLEGAL
method bar () { ...}
Another issue is that Pod directives must be at the beginning of a
line. That would mean having to break the indent in cases like:
method baz ($a, @b) {
#={
Takes $a, applies it to the values in @b
Be mindful of the following:
=item This
=item That
=item And the other thing
}
...
}
Could Perl allow Pod blocks to be indented in #={ } comments? Maybe
the local beginning-of-line in the comment could be considered to be
at the position where the #={ appeared, or at the position of the
first whitespace character after it.. If so, then maybe the no
implicit code blocks restriction could be lifted, so the whole
comment behaves just like an indented =pod block:
method baz ($a, @b) {
#={
Takes $a, applies it to the values in @b
Be mindful of the following:
=item This
=item That
=item And the other thing
This is rendered as code, since it is more indented further
than the initial #={
}
...
}
Thoughts?
Re: Docstrings in Perl 6
2009/5/4 Hinrik Örn Sigurðsson hinrik@gmail.com:
Could Perl allow Pod blocks to be indented in #={ } comments? Maybe
the local beginning-of-line in the comment could be considered to be
at the position where the #={ appeared, or at the position of the
first whitespace character after it.
I meant write /non-whitespace character/ here, of course.
r26668 - docs/Perl6/Spec
Author: hinrik Date: 2009-05-04 18:34:57 +0200 (Mon, 04 May 2009) New Revision: 26668 Modified: docs/Perl6/Spec/S07-iterators.pod Log: [S07] fix the year in Last Modified date Modified: docs/Perl6/Spec/S07-iterators.pod === --- docs/Perl6/Spec/S07-iterators.pod 2009-05-04 16:14:46 UTC (rev 26667) +++ docs/Perl6/Spec/S07-iterators.pod 2009-05-04 16:34:57 UTC (rev 26668) @@ -10,7 +10,7 @@ Contributions: Tim Nelson wayl...@wayland.id.au Daniel Ruoso dan...@ruoso.com Date: 27 Nov 2008 - Last Modified: 20 Apr 2008 + Last Modified: 20 Apr 2009 Version: 5 =head1 Laziness and Eagerness
Re: Docstrings in Perl 6
This message deals strictly with the syntax of '#='-based POD; the
semantics is a separate issue.
--
I'd like '#=' to follow similar rules to what '#' follows, with the
caveat that a line beginning with '#' counts as a single-line comment
no matter what the second character is. Specifically, having the
second character be an = does not transform a full-line comment into a
single line of documentation. This preserves the ability to comment
out a series of lines by prepending a '#' to each of them without
having to worry about whether or not any given line will start doing
strange things. This means that '#=' can never appear at the start of
the line if you want it to denote documentation; but anywhere else is
fine. This should be a simple enough rule for a POD parser to handle
with minimal trouble.
There are additional complications that arise with '#=', such as:
say '#=';
In order to keep a POD parser from having to parse the code as well,
we'd want to say that the #= sequence initiates a POD block that
extends to the end of the line. IOW, the POD parser would end up
with:
CODE:
say '
POD:
';
But if that's the case, how would you ever actually print the
character sequence '#='? Conversely, if you say that the fact that
it's within a string literal means that it counts as string characters
rather than the start of some POD, the POD parser will need to know
how to identify string literals - which, as Perl illustrates, may not
be a simple task.
A possible middle ground might be to say that '#=' starts some POD,
but (e.g.) '\#=' doesn't: where a POD extractor would remove '#=' and
the following POD from the resulting code, it would replace '\#=' with
'#='. So to actually display the '#=' character sequence, you'd say:
say '\#=';
With this in play, you can place '#='-based POD literally anywhere
except at the beginning of a line.
--
With this in mind, I'd propose two forms of '#=', based on what comes
after the '='. If it is followed by one or more '['s, you have
bracketed POD which is terminated by an equal number of ']'s;
otherwise, you have POD which is terminated at the end of the current
line. Note that I specifically said '[' rather than 'a bracketing
character'; this is for the same reason that 'Ccode' is POD markup,
but 'C{code}' isn't. As well, I chose '[' instead of '' to minimize
the need to double or triple up on the encapsulating brackets whenever
inline POD markup is involved. Compare:
#=This text has Iitalics!
#=[This text has Iitalics!]
#=C$x5
#=[C$x5]
Conversely:
#=$x[5] = 7
#=[[$x[5] = 7]]
...which isn't too bad IMHO (and is pretty close to a worst-case scenario).
Finally, I'd want bracketed POD to follow indentation rules similar to
what Hinrik suggested above: if the '#=' is preceded by nothing but
whitespace and every line within the bracketed POD starts with at
least as much whitespace, trim the shortest whitespace off of every
line within the POD.
--
Again, note that the above addresses only the syntax of '#='-based
POD, and not the semantics.
--
Jonathan Dataweaver Lang
S02 Names - Alphabetic?
http://perlcabal.org/syn/S02.html quote- Names [...] * An identifier is composed of an alphabetic character followed by any sequence of alphanumeric characters. The definitions of alphabetic and numeric include appropriate Unicode characters. Underscore is always considered alphabetic. An identifier may also contain isolated apostrophes or hyphens provided the next character is alphabetic. end of quote At a first view 'alphabetic ... include appropriate Unicode characters' sounds like 'characters with Unicode property Alphabetic'. There are some 'Alphabetic' characters not working in rakudo, and some not working in STD.pm (via evalbot), e.g. ा U+093E DEVANAGARI VOWEL SIGN AA (Alphabetic, Spacing_Mark, ID_Continue=Yes) rakudo: FAIL, std: PASS ⓐ U+24D0 CIRCLED LATIN SMALL LETTER A (Alphabetic, Other_Symbol, ID_Continue=No) rakudo: FAIL, std: FAIL Wouldn't it be easier to reference the Unicode properties 1) ID_Start plus U+005F LOW LINE (=Underscore) 2) ID_Continue for identifiers? That's what Unicode 'ID_x' is for. With the nice 'side effect' that combining diacritics are in ID_Continue. Helmut Wollmersdorfer
Re: Docstrings in Perl 6
2009/5/4 Jon Lang datawea...@gmail.com:
With this in mind, I'd propose two forms of '#=', based on what comes
after the '='. If it is followed by one or more '['s, you have
bracketed POD which is terminated by an equal number of ']'s;
otherwise, you have POD which is terminated at the end of the current
line. Note that I specifically said '[' rather than 'a bracketing
character'; this is for the same reason that 'Ccode' is POD markup,
but 'C{code}' isn't. As well, I chose '[' instead of '' to minimize
the need to double or triple up on the encapsulating brackets whenever
inline POD markup is involved.
The end-of-line Pod option would be nice. I assume you mean something like this?
has $.something; #= This is an important attribute
has $!other;
However, I'm not sure why you would want to restrict the multi-line
form to only allow square brackets. The syntactically similar embedded
comments (#{}) allow almost any valid bracketing character pair, and
even Pod allows C«» nowadays.
I'd like '#=' to follow similar rules to what '#' follows, with the
caveat that a line beginning with '#' counts as a single-line comment
no matter what the second character is. Specifically, having the
second character be an = does not transform a full-line comment into a
single line of documentation. This preserves the ability to comment
out a series of lines by prepending a '#' to each of them without
having to worry about whether or not any given line will start doing
strange things. This means that '#=' can never appear at the start of
the line if you want it to denote documentation; but anywhere else is
fine.
That makes sense. Embedded comments (#{}) aren't allowed at the
beginning of a line either for the same reason. I hadn't thought of
that when I wrote my earlier post, so ignore what I said about
changing that bit. :)
As for a Pod parser not knowing what to do in case of say '#=' and
such, I think we should assume that the doc tool /can/ parse Perl
(likely using STD.pm). Extracting comments (be it #, #{}, #=, or #={})
reliably from Perl code without knowing Perl doesn't seem like a
viable option. How do we know that the #= isn't inside a multi-line
string or heredoc, etc? It's easy to do with Pod blocks since they
were designed for that (i.e. = at the beginning of a line is always a
Pod directive), but since the kind of docs we're talking about here
are supposed to be tied to the code they appear next to, it wouldn't
do much good to be able to extract all the comments without
understanding the Perl code around them anyway.
CharLingua and Unicode locales
AFAIR in two Specs 'CharLingua' appears as - maybe - a leftover from the history of Perl 6. Whatever the idea of 'CharLingua' was, something nice-to-have would be support of locale-dependent processing in the sense of Unicode http://cldr.unicode.org/ Helmut Wollmersdorfer
r26674 - docs/Perl6/Spec
Author: lwall
Date: 2009-05-04 23:23:49 +0200 (Mon, 04 May 2009)
New Revision: 26674
Modified:
docs/Perl6/Spec/S05-regex.pod
docs/Perl6/Spec/S12-objects.pod
Log:
[S12] clarify has = semantics
Modified: docs/Perl6/Spec/S05-regex.pod
===
--- docs/Perl6/Spec/S05-regex.pod 2009-05-04 21:20:46 UTC (rev 26673)
+++ docs/Perl6/Spec/S05-regex.pod 2009-05-04 21:23:49 UTC (rev 26674)
@@ -3684,7 +3684,7 @@
Perl 6 will come with at least one grammar predefined:
- grammar Perl {# Perl's own grammar
+ grammar STD {# Perl's own standard grammar
rule prog { statement* }
Modified: docs/Perl6/Spec/S12-objects.pod
===
--- docs/Perl6/Spec/S12-objects.pod 2009-05-04 21:20:46 UTC (rev 26673)
+++ docs/Perl6/Spec/S12-objects.pod 2009-05-04 21:23:49 UTC (rev 26674)
@@ -12,8 +12,8 @@
Maintainer: Larry Wall la...@wall.org
Date: 27 Oct 2004
- Last Modified: 30 Apr 2009
- Version: 81
+ Last Modified: 4 May 2009
+ Version: 82
=head1 Overview
@@ -653,7 +653,12 @@
will be the attribute being initialized, while self refers to the
entire object being initialized. The closure will be called at the
end of the CBUILD only if the attribute is not otherwise initialized
-in either the signature or the body of the CBUILD.
+in either the signature or the body of the CBUILD. The closure
+actually defines the body of an anonymous method, so Cself is available
+with whatever attributes are constructed by that point in time (including
+all parent attributes). The initializers are run in order of declaration
+within the class, so a given initializer may refer back to an attribute
+defined in a preceding Chas declaration.
Class attributes are declared with either Cmy or Cour. The only
difference from ordinary Cmy or Cour variables is that an accessor
