Trailing declarator docs semantics need to be revisited

[lizmat]

S26 states:

Declarator blocks that start with C<#=> attach to the declarator declared at the start of the line immediately before them.

Seems pretty clear cut, now doesn't it. However, the current implementation is way too lenient in attaching, and sometimes attaches to objects one might not expect. Some examples. Please note that all of these examples have been distilled from actual spectests! :-(

class A {
    has $.a; has $.b; #= trailing
}

So, does the trailing doc attach to $.a or $.b? It attaches to $.a!

sub six(Str $param1, Str $param2) {
#= trailing comment for six?
}

So does this attach to the sub six? Or to $param2. It attaches to the sub, whereas $param2 is the last object seen that can have declarator doc.

sub a { }
... many lines of code without declarable objects
#= still attaches to &a

The trailing declarator can be many lines after the object it attaches to, if there's nothing declarable inbetween. This violates S26.

Another example, where trailing docs are before the leading docs:

sub four {}
#| before five
#= after four
sub five {}

I think this should at least be a worry, as this may indicate a mixup on leading/trailing doc, or a copy-pasto.

And a more general issue, that could be considered a bug:

sub a {
#= foo bar
}

That actually attaches the trailing doc to sub a. But the object that lives in $=pod's is not complete: its WHEREFORE is Any, unless you call &a.WHY after which it will be correct. But that's not very useful for rakudoc renderers, as it won't be able to see to what the pod applies to.

I think we should have clearer rules on what the exact semantics are, and have more worries issued in situations where it would be unclear to which object a trailing doc should be attached to.

[vrurg]

sub six(Str $param1, Str $param2) {
#= trailing comment for six?
}

So does this attach to the sub six? Or to $param2. It attaches to the sub, whereas $param2 is the last object seen that can have declarator doc.

I think, unless we make it an error, attaching to the sub is sufficiently logical. The parameters belong to the signature's visual context, i.e. enclosed in parentheses, whereas the pod already belongs to the block context.

But this is the only note I have. Because making this particular case an error would make better sense. As well as the other proposals too.

[alabamenhu]

For what it's worth, I've used the

sub foo($a, $b) {
    #= description of foo
}

In some of my code. I would be genuinely surprised (akin to the my $a; my $b; #= attaches to $a issue) if it didn't. Justification can come from the idea that the declaration of the parameters occurs inside the signature, and so is opaque to the trailing comment which effectively only sees sub foo(…) { … } and thus attaches accordingly.

[lizmat]

But that implies some kind of scoping and style semantics: would the trailing declarator doc also apply to the sub in this case?

sub foo(
  $a, 
  $b
) {
    #= description of foo
}

At the grammar level, there's no functional difference between the two. The only way to make the difference, is to start looking at line numbers. And that becomes very fragile very quickly.

Another solution might be to deprecate trailing declarator doc altogether?

[lizmat]

At the RSC it was decided that the last declarator seen, will be used for attaching trailing declarator doc.

Also that the declarator doc needs to start on the same line as the declarator, or at the start of the line immediately after that. This has now been implemented in RakuAST, and spectests have been adapted accordingly.

[alabamenhu]

At the RSC it was decided that the last declarator seen, will be used for attaching trailing declarator doc.

Whelp, time for me to update a bunch of modules lol. But it's good that some standard has been set so it's clear how it will be handled.