Support refactoring documentation

[jdneo]

#1335

Note that the two css files highlight.css & markdown.css are all copied from https://github.com/microsoft/vscode/tree/master/extensions/markdown-language-features/media

[jdneo]

Since the API is not ready in stable version yet, so we can first start working on the document structure.

@fbricon @snjeza @akaroml @testforstephen @Eskibear Please take a look at the structure and give your feedbacks. Once the structure is determined and checked-in. All the teammates can start filling the content into it.

I'll raise another PR to add the implementation part once the document is finished.

[fbricon]

Question is: how will you map refactoring ids to markdown anchors, such as #extract-to-constant

[jdneo]

That a good question!

Currently, the API will categorize the document according to the CodeActionKind, which is defined as:

export class CodeActionKind {
    static readonly Empty: CodeActionKind;
    static readonly QuickFix: CodeActionKind;

    // --- refactor start
    static readonly Refactor: CodeActionKind;
    static readonly RefactorExtract: CodeActionKind;
    static readonly RefactorInline: CodeActionKind;
    static readonly RefactorRewrite: CodeActionKind;
    // --- refactor end

    static readonly Source: CodeActionKind;
    static readonly SourceOrganizeImports: CodeActionKind;
    static readonly SourceFixAll: CodeActionKind;
}

This is somehow different from our JavaCodeActionKind, so I think we can prepare a general refactor document as a start.

[akaroml]

I guess a mapping mechanism will be needed in the follow-up PR.

[jdneo]

Update: the API has been finalized and should be available in the next VS Code stable version, I'll update the PR after the new version released.

[jdneo]

PR updated...

To navigate to the specific section in the refactoring document, you need to add a keyboard shortcut for a certain refactoring, for example:

{
        "key": "ctrl+shift+alt+e",
        "command": "editor.action.codeAction",
        "args": {
            "kind": "refactor.extract.function",
            "apply": "never"
        }
    }

[fbricon]

Can you please fix the conflict?

[jdneo]

@fbricon Done. Travis linux image failed, seems caused by java 8 runtime.

Should I fix it in this PR?

matrix:
  include:
  - os: linux
    dist: trusty
    jdk: openjdk11
    env:
      - JDK_HOME=~/openjdk11 # force launching JLS using JDK11
  - os: osx
    osx_image: xcode10.1
    jdk: oraclejdk11

[fbricon]

@jdneo please open a different PR

[jdneo]

@fbricon @snjeza The new refactor Introduce Parameter is added. Please take a look.

[fbricon]

Can we check the new API is available (think Theia/Che) before registering the new provider?

[jdneo]

Is there any guidance that we could follow to do such checks?

[fbricon]

I assume something along the lines of if (CodeActionProviderMetadata !== null). But I'm no typescript expert

[jdneo]

CodeActionProviderMetadata is only used as a prarm when register the code action provider, so probably it's not able to be used for API checking. Using env.appName.includes('VS Code')?

// BTW, will theia/che honor the engines field in package.json?

[fbricon]

env.appName.includes('VS Code') is bad, since we'd need to rerelease vscode-java once Theia/Che support the feature.

// BTW, will theia/che honor the engines field in package.json?

That's a question for @benoitf

I don't understand why we can't do a check on CodeActionProviderMetadata (&& CodeActionProviderMetadata.documentation) like we do for https://github.com/redhat-developer/vscode-java/blob/master/src/semanticTokenProvider.ts#L8

[fbricon]

@jdneo if you link to a vsix build, maybe @benoitf can test it (display the refactoring menu, see there are no errors)

[jdneo]

Hi @benoitf,

Would you mind to help test this feature? Here is the vsix link. To test it, you can open a Java file, right click in the editor and click Learn more about Java refactorings (if it exists in the context menu).

More details can be found in the gif

Thanks

[benoitf]

here is a link to try this vsix with che online: http://che.openshift.io/f/?url=https://gist.githubusercontent.com/benoitf/dcc2fa363b37161f5c8105a8e439a389/raw/55c6c7b117614c45d12a576d8159437c3afd923e/devfile.yaml

[benoitf]

custom documentation does not appear but it's expected as not yet supported

[jdneo]

Thank you @benoitf!

@fbricon Seems that a RefactorDocumentProvider is registered for nothing.

[fbricon]

Thanks for the cool feature @jdneo!