contributes.configuration configuration property schema: Dropdown menu poorly specified (enum / enumDescriptions / enumItemLabels)

[Chealer]

VS Code allows extensions to create settings with predetermined options based on a list of presets. The Contribution Points page's Configuration property schema subsection documents how to do that using the enum / enumDescriptions / markdownEnumDescriptions / enumItemLabels properties. But given how funky the schema is, it would be best to properly specify that part.

Here are a number of specific issues:

1. There is no code example of enumItemLabels.
2. enum is mentioned but not specified.
3. markdownEnumDescriptions is not mentioned in the title.
4. "will be rendered as Markdown" would be more accurate as "will be parsed as Markdown".
5. The relationship between these 4 properties is unspecified. What happens if both markdownEnumDescriptions and enumDescriptions are set, for instance?

Also, the following:

The workbench.iconTheme setting uses both enumDescriptions and enumItemLabels. In the screenshot below, the hovered option has the item label "None", with enum description "No file icons" and enum value null.

…would be clearer as:

For example, the workbench.iconTheme setting shown below uses both enumDescriptions and enumItemLabels. In this screenshot, the hovered option has the item label "None", with enum description "No file icons" and enum value null.

I wish this report is the occasion for a general review of that section but understand that the scope is a little wide. Feel free to consider this as solved once the first specific issue is solved. I will file different tickets for any remaining problems if needed.

[ntrogh]

@Chealerappreciate you writing this extensive issue description.

[Chealer]

The change does solve at least #1, #3 and #4. Thank you very much @rzhao271 :-)

[rzhao271]

I'm not sure what you'd like for item 2. Are you looking for allowed types, for example? 5 is specified with the phrase "instead of". I'll add a note that the Markdown field overrides the non-Markdown field.

[Chealer]

Thanks again @rzhao271

I'm not sure what you'd like for item 2. Are you looking for allowed types, for example?

Yes, that's partially specified but only implicitly. If it's an array of different strings, that should be explicitly specified, specifying how non-unique values are treated. If the dropdown menu contains the same number of items as enum, it would clarify to indicate that.

5 is specified with the phrase "instead of". I'll add a note that the Markdown field overrides the non-Markdown field.

Thanks, that's clearer, but it's still short of a real spec. Due to the schema's funkiness, it remains unclear how VS Code would treat for example the following:

{
  "settingsEditorTestExtension.enumSetting": {
    "type": "string",
    "enum": ["first", "second", "third"],
    "enumDescriptions": ["The first enum", "The second enum", "The third enum"],
    "markdownEnumDescriptions": ["The first enum *ONLY*"],
    "enumItemLabels": ["1st", "2nd", "3rd"],
    "default": "first",
    "description": "Example setting with an enum"
  }
}