Rakudoc Delimited Block Comments

[finanalyst]

Rakudoc block comments do not work consistently. A =begin comment and =end comment sequence with an embedded =begin code / =end code generates a compiler error. If 'comment' is substituted for 'pod' in the above, there is no error. …

According to the specification, a delimited block starts with =begin BLOCKNAME and =end BLOCKNAME

=begin comment and =end comment sequence generates a Pod::Block::Comment as expected. However, it is not possible to embed another delimited block within such a comment - the compiler generates an error. By contrast, a named block, such as begin pod / end pod sequence will allow for embedded delimited blocks.

There is no indication of multiline comments being a part of the specification. However, the current behaviour of Rakudo is inconsistent and there is no reason for treating Pod::Block::Comment any differently to other delimited blocks. How the multiline comment is rendered is for the renderer to decide, not the compiler.

So, I suggest this Comment block behaviour is a compiler error. …

[raiph]

If 'comment' is substituted for 'pod' in the above, there is no error.

Huh?

[finanalyst]

So lets create a file with

=begin pod
something
=begin code
my $x='sss';
=end code
=end pod

This compiles properly. If you inspect the Pod::Block for the =begin pod, it is a named block with name 'pod'. Now lets add a multi-line comment (I suppose I was a bit inaccurate earlier when I said 'substitute')

=begin pod
=begin comment
something
=begin code
my $x = 'sss';
=end code
=end comment
=end pod

This causes a compile error.

Expected "=end comment" to terminate "=begin comment"; found "=end code" instead.

Now upon inspecting a pod tree with a comment, the relevant Pod::Block is Pod::Block::Comment

So the behaviour of the Comment block is different to the behaviour of the Named Block.

I would expect them to be the same.

Hope this clarifies things

[lizmat]

In RakuAST this now generates:

[Pod::Block::Named.new(name => "pod", config => {}, contents => [Pod::Block::Comment.new(config => {}, contents => ["something\n=begin code\nmy \$x = 'sss';\n=end code\n"])])]

So it appears this will be fixed automatically when using the RakuAST grammar as default.

[lizmat]

I think this can be closed in the meantime?

[finanalyst]

if RakuAst is correct then this can be closed