Add POD overview on hover in code and autocomplete

[antoinemarechal]

Having the documentation at hand would be a nice addition. This should be achievable with the perldoc utility using variations of perldoc -T -MPod::Simple::HTML <other arguments>. The formatter would default to Pod::Simple::HTML but would be customizable in the extension settings.

This feature could cover the perlfunc, perlapifunc, perlvar (respectively with the arguments -f, -a and -v) and modules.

Regarding the hover/autocomplete of module subroutines/constants/variables, it could just display the documentation of the whole module. As this level of granularity is not ideal, the process could be made a little more smart about those symbols. The idea would be to search after =headX or =item occurences followed by the symbol name in the POD and if results are found, the documentation would be scrolled to the first occurence. As the results might not be perfect, this could be an optional feature to toggle in the settings.

[bscan]

Thanks @antoinemarechal ! A first version is now in version 0.7.6, and.documentation is displayed on hover and autocompletion (see examples below). I did include the narrowing down to individual subroutines/methods.

I avoided perldoc for a few reasons. First, finding the perldoc executable might be tricky since users specify only their perl path, which may be a wrapper for docker or other remote execution. Pod::Perldoc->run or Pod::Simple::SimpleTree are options, but I'd still need to add Pod::Markdown as a dependency. More importantly, since people will be flipping through autocomplete suggestions, this needs to be very fast and calling out to perl each time could be prohibitively slow.

I wrote a perldoc extractor and a conversion from POD to Markdown entirely in Typescript. This also gives me full control over the display, which is convenient. For example I map =head1 MyItem to ### MyItem instead of # MyItem because the condensed titles look better in a space-limited hover format. There are probably edge cases not yet covered, but most of the basic POD functionality is working well, including code blocks, C<> / B<> style elements, and all the pod = commands. If anything is displaying incorrectly, let me know. Thanks!

Follow-on work could include support for parsing perlfunc, perlapifunc, and perlvar. These are simply giant pod files (e.g. https://perldoc.perl.org/perlvar.txt ), so the pod-to-markdown converter should work here too. Long term, the custom parser would also enable the ability to extract non-POD documentation, such as inline comments that follow the subroutine definition.

I'll close this ticket for now, but commentary, suggestions, and issues are more than welcome. Thanks!

[bhuynhdev]

Hi, I want to revisit this and comment with my specific issue. I am not sure if this is a bug or not-a-feature-yet, but the POD documentation for a specific sub isn't really working. For module, it works amazing (as shown in the File::Copy example)

But for a sub like this:

=head2 sessionkeeper

The session manager code

=head3 ARGS

=over 4

=item session_id
Integer Id of the session

=cut

sub sessionkeeper
{
    my ($self, %args) = @_;

    ...;
}

The hover documentation only includes the head2 text, and do not include any head3 or over texts

If I use LSP Hover, this is what I get

(subroutine) sessionkeeper

#### sessionkeeper

The session manager code

[bscan]

Hi @bhuynhdev, yes this is a current limitation. When looking up a subroutine, it only includes the POD sections with title that match the subroutine. Basically, it doesn't have any logic to say that a head3 probably belongs with the prior head2 section. In your example, the POD is all grouped together before the sub, but a common use case is all together at the end of the file. And then it's tricky to figure out which subsections are relevant for a specific sub. More details here: #134 and there is a pull request in progress to address this exact issue: #142

It won't solve everything because there's no real standard for how to organize POD, but I think it'll go a long way to improving the situation.