Formatting of declarator blocks in subroutine's parameters

[uzluisf]

Declarator blocks (#=) for a subroutine's parameters are formatted as H2-level headings while the subroutine's name is formatted as H3-level heading. This makes them seem out of place. Ideally, the subroutine's name would be formatted with a heading level higher than anything else that belongs to it.

Example: https://gist.github.com/uzluisf/ec9fa34e603bdc11d5e84642e6d74ddc

[wolverian]

Additionally, the argument name is missing altogether from the Markdown output.

Edit: the output is so weird I completely misread it. 😄 The name is there, as @uzluisf says, it's just difficult to see.

[softmoth]

Thanks for this bug report. I think my reason for this was to copy the way Pod::To::HTML behaved at the time. This should be revised. I welcome any patches should you get to it before I do.

[softmoth]

Unfortunately, it appears that fixing this requires a (major?) fix to rakudo. The contents of $=pod are a flat array, with no way to determine that a sub belongs to the class before it, and no way to identify that the variable is a parameter of the subroutine or method rather than a stand-alone. There is no nesting. The params are not in the contents of the routine they belong to.

#| asdf1
module Asdf1 {
    #| Sub asdf
    sub asdf(
        Str $asdf1,     #= Positional, not optional

        #| This one is named & _really_ optional
        Str :$asdf2? = 'asdf'
    ) returns Str
    {
        return $asdf1 ~ $asdf2;
    }
    my Str $foo = "gotcha!"; #= This could be another param
}

for $=pod[] {
    say (.leading, .trailing, .WHEREFORE.perl)
        .map({ "[{$_ // ''}]" })
        .join(' ');
}

I can't think of a hack to fix this in the short term. Long term I'm sure there are bugs open in rakudo for this, but I don't know which. I'd appreciate anyone linking relevant rakudo bugs here.

[dwarring]

I've raised a Rakudo ticket