Refactoring documentation contribution point

[mjbvz]

Problem

Many language/extension implement really cool refactorings, but many users never discover these or figure out how to reliably trigger them.

Proposal

Add a way for an extension to contribute documentation for their refactorings. Our goal here would be to help users reach the documentation and leave the presentation of the documentation up to extensions themselves.

Target UX

Let users explicitly request to see the refactoring documentation from the existing code action refactor menu. This could be as simple as a Learn more entry at the bottom of the refactoring menu.

The learn more action would do the following:

• If we are in a language that only has one refactoring documentation provider, then show that documentation directly
• If we are in a language with multiple refactoring documentation providers, show a quick pick so that users can tell us which documentation they are interested in (this is similar to how our remote documentation works today)

API

Current proposal

The current proposal is the add a documentation field to CodeActionProviderMetadata that let's extension surface a command that shows documentation:

export interface CodeActionProviderMetadata {
	/**
	 * Static documentation for a class of code actions.
	 *
	 * The documentation is shown in the code actions menu if either:
	 *
	 * - Code actions of `kind` are requested by VS Code. Note that in this case, we always pick the most specific
	 *  documentation. For example, if documentation for both `Refactor` and `RefactorExtract` is provided, and we
	 *  request code actions for `RefactorExtract`, we prefer the more specific documentation for `RefactorExtract`.
	 *
	 * - Any code actions of `kind` are returned by the provider.
	 */
	readonly documentation?: ReadonlyArray<{ readonly kind: CodeActionKind, readonly command: Command }>;
}

---

original proposal

I see two possible ways this could be implemented:

Through a contribution point

Create a new documentation.refactoring contribution point that lets extension define a command that shows the documentation:

  "contributes": {
    "documentation": {
      "refactoring": [
        {
          "title": "%documentation.refactoring.title%",
          "when": "typescript.isManagedFile",
          "command": "_typescript.learnMoreAboutRefactorings"
        }
      ]
    },
}

Through a new refactor.documentation code action kind

Define a special code action kind called refactor.documentation. If an extension returns a code action with this kind, then we could surface this using some special UI in the refactor menu

(extensions would be expected to return the refactor.documentation action whenever refactorings are requested)

/cc @kieferrm
/cc @jrieken for api
/cc @misolori for ux

[mjbvz]

@akaroml @DanTup Also interested to hear if this is something you would find helpful for your extensions and if you have and other ideas about how this documentation could be presented

[DanTup]

I don't know that I have the data to populate this, though the idea sounds good to me.

I think there many other places that exposing docs would be great - I opened #71541 previously, but there it was resolved as a dupe of another case that never got a concensus on the fix (which is a shame, because I think it's a tiny change with a large impact for users).

[kieferrm]

I'm in favor of the contribution point, but both approaches work.

[akaroml]

While the static contribution point would work perfectly, the refactor.documentation could have more potential by allowing vscode to:

1. Specify more context, e.g. the position where the documentation is requested
2. Have a special UI to show the documentation, e.g. documentation overlay without switching to another editor tab.

This also allows the language server to generate more precise documentation according to the context.

So I prefer the LSP way.

[jrieken]

My preference is for something static but similar to the previous approaches we need to make sure that extensions can provide this - tho the approach seems to have the right amount of indirection for this.

I am wondering if there are synergies with the work we are doing around extensions adding "getting started" or "playground parts" etc?

[mjbvz]

@DanTup If you have a webpage that documents refactorings, you could link users to that. It doesn't need to be anything fancy to start off, just a list and a quick description of what each refactoring does

---

@akaroml Good points about the LSP support.

One other consideration with using code actions to return documentation is that other editors would likely not know what to do with the returned Refactor.documentation items besides showing them inline in the code action list (which is probably not what you want)

---

@jrieken I also like the idea of idea of integrating this with our other documentation exploration but worry that may take a while to finalize. Maybe we should try delivering a scoped solution that only handles code actions so that Java and others can play around with the idea, and then look into how this would fit with our larger documentation/getting started experiences?

[akaroml]

@jrieken Thank you for bringing up the synergy idea! I do see those three approaches sharing similar goals. As an extension author, I really appreciate the platform providing a clear picture of how those UI elements can work together and serve different use cases!

And here to share some of the challenges and use cases.

Code Actions Challenges

1. Visibility/Discoverability
   Provide a full list of what's available. And CodeAction.disabled will help serve that purpose.
2. Triggers
   We also find it challenging for the users to figure out how a code action could be triggered. E.g. the "Invert Boolean" could be triggered by placing the cursor inside the expression, then the whole expression will be inverted because we infer the biggest possible from the cursor, or, the users can also select a part of the expression, then only the selected part will be inverted.
   The challenge here is how we could educate the users about the differences. I think the discussion in this particular issue can help provide a place to document that behavior explicitly.

Getting Started

1. Key Binding Challenges
   This is so important for experienced users. We have enough key binding extensions but the challenge here is that vscode and other editors/ides do not have 1:1 feature parity and we will have missing keystrokes for sure. And as the love for vscode grows, users would want to learn and adapt to vscode conventions.
   One idea here is to let the language extension handle the missing key bindings. For example, users may try F8 to start debugging while it does nothing by default. Then the Java extension could respond by hinting the user "Are you trying to start debugging? To do so, press F5 instead.".
2. How to challenges
   We identify common tasks that users would want to perform and provide documentation accordingly. The challenge here is how users can find them. It's like digging something in a library, and a search based tool can help.
   The idea here is to allow an extension to contribute getting started documentation and users can locate those entries by typing some keywords.

Rich Tutorial Experience

Students are a large group in our user base. And tutorials are great for them to learn and practice. Now the best we can do is to show the documentation and an editor side by side. It's already working but it could be even better if the documentation can interact with the editor, and I see that a playground.

@mjbvz Agreed. We'll always happy to try new APIs and see how they work.

[jrieken]

@mjbvz 👍 for moving fast. Circling in @eamodio for some "getting started" ideas that point in a similar direction

[mjbvz]

@jrieken I've changed the contribution point proposal to be more generic to better support that:

  "contributes": {
    "documentation": {
      "refactoring": [
        {
          "title": "%documentation.refactoring.title%",
          "when": "typescript.isManagedFile",
          "command": "_typescript.learnMoreAboutRefactorings"
        }
      ]
    },
}

Here's how this is rendered in the editor: