Show title and description in completions

[srivastava-diya]

Part of #147

Opening this as a draft because it covers the title and description part of the issue.

What this does

Completions now show the title and description from the schema in their documentation panel.

• Property completions show every title and description that applies to the property, the same as Hover. With

  "name": { "allOf": [{ "title": "A" }, { "title": "B" }] }

  the completion for name shows both "A" and "B".

• Value completions show only the value's own title and description. With

  "color": {
    "title": "Color",
    "anyOf": [
      { "const": "red", "title": "Red" },
      { "const": "blue" }
    ]
  }

  the completion for red shows "Red" and not "Color". blue has no documentation.

• A completion with no title or description has no documentation at all.

How

• The title/description formatting that Hover used is moved into a small shared function, describeAnnotations, so Hover and completions format things the same way. Hover's output is unchanged.
• PropertyCompletionsProvider and ValueCompletionsProvider set documentation on their items using that function.

Tests

Added 12 tests across the property and value completion test files, including the two examples above.

[srivastava-diya]

Things that I have left for now and need a little feedback on,

1. Deprecated: Support deprecated #136 already adds deprecated tags to property and value completions, and it changes the same lines as this PR. so i left that.

2. Other things: what did you have in mind? One option is offering default and examples as value completions. Related: Show default and examples in hover #88 is about showing default and examples in Hover. Since this PR makes Hover and completions share the same formatting, should the completion documentation show them as well once Show default and examples in hover #88 is done, or should that stay Hover-only?

3. Hover: are you okay with Hover using the shared function, or would you rather I leave Hover alone and keep the formatting inside the completions code?

[srivastava-diya]

Some more suggestions on the Other things that we can do

• per-value descriptions from enumDescriptions / markdownEnumDescriptions
• offering default and examples as value completions, with the default marked as "Default value"
• a short detail next to the label from completionDetail / enumDetails
• schema-controlled ordering and hiding with suggestSortText / enumSortTexts / doNotSuggest
• inserting a starting value along with a property name
• sending plain text instead of markdown to editors that don't support markdown

I'd rather do these as separate PRs like by creating sub issues from this main issue. Which ones are worth doing, and is there an order?

[jdesrosiers]

Looks good so far. Do a rebase. There are a couple of things I merged today that I think will affect this.

Let's keep this PR to title and description.

• per-value descriptions from enumDescriptions / markdownEnumDescriptions
• a short detail next to the label from completionDetail / enumDetails
• schema-controlled ordering and hiding with suggestSortText / enumSortTexts / doNotSuggest

👍 These are all part of implementing the vscode vocab

• offering default and examples as value completions, with the default marked as "Default value"

I don't think we want those to be completions, but there might be another LSP feature that makes sense. I'm thinking about something like the placeholder text in an HTML form that's greyed out and disappears when you start typing.

• inserting a starting value along with a property name

Maybe. I can decide if that's something I want it to do, but I'm leaning toward no.

• sending plain text instead of markdown to editors that don't support markdown

We should definitely look into this one.

[srivastava-diya]

Looks good so far. Do a rebase. There are a couple of things I merged today that I think will affect this.

Rebased on the latest main and pushed.

One thing came up in the rebase. Deprecated support and this PR both set the completion's documentation. I resolved it so that a deprecated completion with a deprecation message shows only that message, same as before this PR.

Is that what we want, or should a deprecated completion show its title and description together with the deprecation message?

👍 These are all part of implementing the vscode vocab

Okay, I'll open separate issues for those keywords.

I don't think we want those to be completions, but there might be another LSP feature that makes sense. I'm thinking about something like the placeholder text in an HTML form that's greyed out and disappears when you start typing.

Makes sense, I'll leave default and examples out of completions.

Maybe. I can decide if that's something I want it to do, but I'm leaning toward no.

Okay, I'll leave that one alone unless you decide you want it.

We should definitely look into this one.

I'll open an issue for sending plain text to editors that don't support markdown.

[jdesrosiers]

Is that what we want, or should a deprecated completion show its title and description together with the deprecation message?

Show everything, but lead with the deprecation.