Show Sub-Subsections in Subroutine Hover Documentation

[Aequitosh]

Something I have noticed while writing docstrings with POD is that sub-subsections are cut from the result of textDocument/hover. It's probably best if I demonstrate this with an example.

Let's say we have the following subroutine and docstring:

=pod

=head3 foobar

    $result = foobar(%params)

The C<foobar> subroutine does the I<foo bar> in a very particular manner.

You may supply additional flags in C<%params>; see below.

=over

=item C<first>

If you pass C<first =E<gt> 1>, the I<foo bar> is done in I<baz> mode.

=item C<second>

If C<second =E<gt> 1>, you get additional output depending on the I<foo bar> performed.
Mostly useful for debugging purposes.

=back

=cut

sub foobar {
    my (%params) = @_;
    # [...]
}

Everything from =over onward gets cut off (or isn't included) in the hover documentation:

The same also goes for subsections after =head3, as in =head4, =head5 and =head6. I would expect everything that's within the section for the foobar subroutine be included in its docstring.

Maybe I'm holding it wrong, so please correct me if I messed up somewhere here.

If this is something that PerlNavigator does indeed want to support / fix, I can offer a helping hand, though my TypeScript is a little rusty these days.

[bscan]

Hi @Aequitosh. Sure, contributions would certainly be welcome in this area. POD parsing can be challenging in general, and I wrote this POD parser from scratch (with the assistance ChatGPT), so it isn't as full featured as the ones written in Perl. I took a look and confirmed this specific issue occurs in WWW::Mechanize as an example. This ->new() section references following parameters, but they aren't displayed:

For this problem in particular, it's tricky one. The parser does keep track of which elements are in lists, but only uses this information for converting POD to Markdown, not for detecting which sections are nested or relevant. See the state.inList boolean variable which tracks this. Example:

Open to ideas and contributions on how to improve this, or any other POD related issue. Thanks!

[Aequitosh]

Thanks for your detailed response! I'll have a more closer look at the code soon, perhaps I can help. This is definitely something I'd find handy, so I wanna get my hands dirty for it.

[Aequitosh]

@bscan I'm currently polishing the last remaining few bits of the PR I'm going to submit, so I wanted to ask: Could you please elaborate on this here? What kind of leading comments are those? I haven't been writing Perl for that long, so I haven't encountered those yet. Would be great if you could provide an example, too! Thanks a bunch.

[bscan]

Thanks @Aequitosh! Here's an example of the comment format. I'm not sure how common it is in the wild, but my $work has a number of examples. It's a very specific format, so I tried to keep the parsing code for it separate from the remainder of the doc parsing code. The regex to find it is fairly complex, but it allows us to use the fairly fast regex engine instead of iterating line by line.

[Aequitosh]

Ah, I see! Thanks a bunch, I'll make sure this remains supported. I'll probably keep it separate from the POD parser as well. Expect a PR this week. :)