Autocompletion should return javadoc in Markdown

[fbricon]

See https://code.visualstudio.com/updates/v1_17#_javascript-and-typescript-intellisense-now-supports-markdown

We basically need to revert #215. On the server side, the type of documentation should depend on whether the client supports it. Need to check the protocol.

[fbricon]

@aeschli https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#completion-request doesn't specify the documentation format, shouldn't that be an attribute of TextDocumentClientCapabilities.completion.completionItem (next to snippetSupport)? Else we're gonna need to add a new server preference to let clients tell the server whether it should return plain text or markdown.

[aeschli]

That's a new API in VSCode that we still need to adopt in the language server protocol. For now, documentation format is still text.

[fbricon]

I like my javadoc to look good. @gorkem wdyt about starting the server with a -Dcompletion.documentation.markdown=true flag, so that we can leverage that vscode feature until it makes it to the protocol?

[fbricon]

@aeschli so if the server returns markdown in the documentation field, it's still rendered as plain text (using insiders 1.18). How is this supposed to work?

[Trace - 16:48:00] Received response 'completionItem/resolve - (29)' in 24ms.
Result: {
    "label": "String - java.lang",
    "kind": 7,
    "documentation": "The String class represents character strings. All string literals in Java programs, such as \"abc\", are implemented as instances of this class.\n\nStrings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared. For example:\n\n>     String str = \"abc\";\n\nis equivalent to:\n\n>     char data[] = {'a', 'b', 'c'};\n>          String str = new String(data);\n\nHere are some more examples of how strings can be used:\n\n>     System.out.println(\"abc\");\n>          String cde = \"cde\";\n>          System.out.println(\"abc\" + cde);\n>          String c = \"abc\".substring(2,3);\n>          String d = cde.substring(1, 2);\n\nThe class String includes methods for examining individual characters of the sequence, for comparing strings, for searching strings, for extracting substrings, and for creating a copy of a string with all characters translated to uppercase or to lowercase. Case mapping is based on the Unicode Standard version specified by the `Character` class.\n\nThe Java language provides special support for the string concatenation operator ( + ), and for conversion of other objects to strings. String concatenation is implemented through the StringBuilder(or StringBuffer) class and its append method. String conversions are implemented through the method toString, defined by Object and inherited by all classes in Java. For additional information on string concatenation and conversion, see Gosling, Joy, and Steele, *The Java Language Specification*.\n\nUnless otherwise noted, passing a null argument to a constructor or method in this class will cause a `NullPointerException` to be thrown.\n\nA String represents a string in the UTF-16 format in which *supplementary characters* are represented by *surrogate pairs* (see the section Unicode Character Representations in the Character class for more information). Index values refer to char code units, so a supplementary character uses two positions in a String.\n\nThe String class provides methods for dealing with Unicode code points (i.e., characters), in addition to those for dealing with Unicode code units (i.e., char values).\n\n *  **See Also:**\n    \n     *  java.lang.Object.toString()\n     *  java.lang.StringBuffer\n     *  java.lang.StringBuilder\n     *  java.nio.charset.Charset\n *  **Author:**\n    \n     *  Lee Boynton\n     *  Arthur van Hoff\n     *  Martin Buchholz\n     *  Ulf Zibis\n *  **Since:**\n    \n     *  JDK1.0",
    "sortText": "999999164",
    "filterText": "String",
    "insertText": "String",
    "insertTextFormat": 2,
    "textEdit": {
        "range": {
            "start": {
                "line": 58,
                "character": 2
            },
            "end": {
                "line": 58,
                "character": 7
            }
        },
        "newText": "String"
    }

[aeschli]

@fbricon We first will have to add new API to the LSP. Either a new property documentationFormat: plainText | markdown or new property type: documentation: string | MarkdownString.
There will also be a client capability. Not that, ideally, your server can support either format, based on the client capability.

[fbricon]

Migrating to LSP4J 0.4.0's new API should allow us to support this feature.

[fbricon]

Depends on eclipse-jdtls/eclipse.jdt.ls#654