Quick documentation look-up for packages

[RepliedSage11]

There is functionality in IntelliJ and VS Code that allows to get quick package documentation from a package.json file.

I think this would be a useful addition to the Pub IDE extensions.

My main use case is package upgrades. Right now I have to run flutter pub outdated and then manually lookup every package on pub.dev to find its changelog. I would like to be able to see the outdated packages right in the pubspec.yaml file with quick access to the changelog and documentation.

This will also promote good practices of keeping your dependencies up to date if you can just take a glimpse at your pubspec instead of running a console command each time, which some folks might not do very often.

Here are the IntelliJ capabilities when working with package.json

[lrhn]

This is a tooling issue, not something controlled by Pub.
It might be the analysis server. (Or it might be the IDE plugin, I don't know who provides what for pubspec.yaml files.)

[sigurdm]

cc @DanTup would this be the lsp server or the vscode plugin providing this?

[DanTup]

It depends on the specifics, but most likely if we did something here it would be in the analysis server (it's slightly more restricted for VS Code, but means all LSP clients get the functionality instead of only VS Code). It's not clear to me exactly what the UI is in the screenshot above, but the analysis server can provide hovers, inlay hints and CodeLens for pubspecs (although none of those are currently implemented).

There's also a similar/related issue at Dart-Code/Dart-Code#1977.

[bwilkerson]

It's not clear to me exactly what the UI is in the screenshot above ...

Me either. @RepliedSage11 could you provide more information about how you'd like to be able to see this information, both in VS Code and in IntelliJ?

[RepliedSage11]

The UI in the screenshot is the tooltip displayed when hovering over one of the dependencies in a package.json file. It is rendering the readme file of the package with additional info from npm like the latest available version.

I suspect for the pub extension it would be sufficient to show links to pub.dev and the latest version of the package, as well as some quick actions like upgrading an individual package or upgrading all packages.

@bwilkerson

[DanTup]

Ah, thanks - I think I was thrown by the rounded corners.

I think there are probably two parts to this:

1. Show documentation about a package when hovering
2. Show notifications when pub packages can be updated

I think the first one would either need a request to the Pub API during computing of the hover, or reading directly from the readme.

The second, we might already have some of the data for - we run pub outdated to get version numbers to use in the code completion. There are multiple version numbers that might be interesting though - because there may be newer versions that you can update to without changing any other constraints, or newer versions that require changing other packages. It might be better to encourage running something like pub upgrade (or pub upgrade --major-versions) instead of updating individual packages (although currently these commands are client-side in VS Code, and not part of the server).

[bwilkerson]

I think the first one would either need a request to the Pub API during computing of the hover, or reading directly from the readme.

Or, per the comment above, just include a link to the package's site on pub.dev.

If we can read the comment directly from the readme then I suspect that would be faster, and would work without a network connection.

It might be better to encourage running something like pub upgrade ...

I agree.

We could add a banner in the hover stating that there are newer version that might be compatible that includes the suggestion to run pub upgrade.

[FMorschel]

Or, per the comment above, just include a link to the package's site on pub.dev

This is done now after Dart-Code/Dart-Code#2785 got closed. Not on hover but you can CTRL + Click on the package name.

[RepliedSage11]

encourage running something like pub upgrade (or pub upgrade --major-versions) instead of updating individual packages

This makes more sense in Dart's case since AFAIK in npm you can't have incompatible dependency constrains since every package can just download a copy of a dependency with whatever version they need, so you can update individual dependencies while ignoring others.
Dependency updates in Dart make sense only when updated as a whole, so maybe we should think about something similar to the table that is printed by flutter pub outdated but inside the IDE?