Synopsis 26 <http://design.perl6.org/S26.html#Declarator_blocks> says of declarator blocks:
> A declarator can have multiple leading and/or trailing Pod comments, in which case they are concatenated with an intermediate newline when their object's .WHY return value is stringified But the current implementation just concatenates them with a space, and the test suite validates this: https://github.com/perl6/roast/blob/master/S26-documentation/why-leading.t It also says: > Formatting codes provide a way to add inline mark-up to a piece of text within the contents of (most types of) Pod block (including all declarator blocks). I can't find a test relating to this, but the current implementation doesn't seem to allow it. When Pod::To::Text sees a declarator block, its contents are just a list containing a single Str, which contains verbatim formatting codes. In other words, given this code: #| Calculate the number of ways of selecting C<$k> elements from #| a list of C<$n> elements. The formula is #| #| n! #| -------- #| n!(n-k)! sub choose {...} I'd expect --doc to be able to format the comment appropriately. But by the time Pod::To::Text sees the block, it only sees the string: "Calculate the number of ways of selecting C<\$k> elements from a list of C<\$n> elements. The formula is n! -------- n!(n-k)!" which is unhelpful. Normally I'd assume this is just NYI, but the test suite seems to disagree with the synopsis about whitespace, so I figured I'd ask - should it work like I expect, or is the synopsis out of date, or? (Using perl6 and moarvm versions more recent than 2015.07.2, but I don't recall exactly which. Sorry, don't currently have access to that machine, so this is from memory.)