'Create Table of Contents' code action should not be suggested always

[artempyanykh]

• Change the code to suggest 'Create ToC' when either
  • the requested range overlaps with the 1st line of the document,
  • code action kind is 'source'.
• 'Update ToC' should be suggested anywhere in the document still (as is now).
• Update the docs

[rchl]

What does suggest 'Create ToC' only on the 1st line of the document mean exactly?
That the code action should only be returned if the asked for range includes first line?
If that's the case then you should also ensure that the code action is returned regardless of the asking range if explicitly requesting source code actions. Otherwise this change would cause issues for the Source actions context menu item.

[artempyanykh]

Thanks for mentioning source code action kind @rchl! I've updated the todos to reflect the condition more precisely, e.g. either source or the range overlapping with 1st line of the document.

[David-Else]

Is it possible that Marsksman could not suggest creating a TOC at all, but instead it is available as an LSP command? If the document had a TOC it could still provide a code action to update it. I think this would be the best solution as most documents don't have a TOC and an LSP command seems a more natural solution?

Helix is about to get commands added, and Neovim has them already, I don't know the status in other editors, but it is official LSP spec so it should be available.

[rchl]

I think that a code action of source type is appropriate for this use case.

Custom commands typically require a bit of glue code on the client side so I'm not sure what would be the benefit of that over source code actions.

[David-Else]

@rchl Are you saying that custom commands can't just be called via the client, they need specific code on the client side? If so, that would be bad news.

[rchl]

LSP servers can only tell clients the command IDs they support (for example marksman.create_toc). The client neither has a nice title for that command nor a schema to know what arguments to pass (in case command takes arguments) so typically those missing bits need to be added manually to the client configuration.

Clients could expose command IDs and let users trigger them but that wouldn't be very useful in most cases as many commands require arguments.

[artempyanykh]

Marksman now supports user- and project-level config. With #109 users who don't care about ToC can disable it globally in their user-config and then re-enable on a project-by-project basis if needed.

By default, ToC is enabled but this is something to potentially reconsider in future.

Re: using code action's range and context to decide whether to suggest the ToC code action or not -- the problem here is that different editors, different LSP clients and different plugins all behave differently and have their own UI/UX for code actions. I hope that the config option will address 90% of the UX problems with ToC code action (particularly for non-VSCode/non-ST users where LSP clients don't do any filtering of code actions).

Closing this issue. It's OK to reopen it though, if somebody feels strongly about it.