On Wed, May 6, 2009 at 3:42 PM, Leon Timmermans wrote:
> Most people seem to lean towards the pod comments, though I disagree
> with it on a simple ground: aesthetics. Python docstrings aren't just
> useful, they are reasonably pretty too, #={} isn't. In fact I'd say
> it's pretty fugly. I think t
2009/5/4 Damian Conway :
>
> Each approach has advantages and disadvantages.
> Feedback via this forum would be most welcome.
>
Most people seem to lean towards the pod comments, though I disagree
with it on a simple ground: aesthetics. Python docstrings aren't just
useful, they are reasonably pre
2009/5/4 Jon Lang :
> 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
> lin
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, hav
2009/5/4 Hinrik Örn Sigurðsson :
> 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 /
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
Bl
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 orde
On Mon, May 4, 2009 at 12:30 PM, Charles Bailey
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 t
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
* Hinrik ??rn Sigur??sson (hinrik@gmail.com) [090504 10:45]:
> 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 inlin
These two (generalized Pod comments and C 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 Per
* 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
> >
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 docum
13 matches
Mail list logo
