Render setting descriptions as markdown

[roblourens]

In the new settings editor, setting descriptions should be rendered as markdown. We should decide when to use quotes, backticks, and links, then make a pass through all settings to make them consistent.

• Links

  • We can allow arbitrary links in description markdown, or add a documentation field to the settings schema which would be a URL to some docs. Then we can show a "See also" link in a standard location to settings that have this in the settings editor.
  • References to other settings should be links. Clicking the link could search for that setting, and filter the list to just that setting, or scroll to it. (Is that a good experience? How do you go back?) How do we specify a "reference to a setting"? If we scroll to that setting, what happens if the referenced setting is not in the current view (search, scope, "modified only" etc)?

• Enum descriptions

  • We currently don't show enumDescriptions anywhere. These have useful info but settings are inconsistent. Some settings duplicate this info in their description, some don't. Example of setting with duplicated info: https://github.com/Microsoft/vscode/blob/master/src/vs/editor/common/config/commonEditorConfig.ts#L678
  • We should add the enums and enumDescriptions to the bottom of the setting description, and audit all setting descriptions to remove the duplicated info. It should be displayed like this for the new and old settings editors.
  • Some settings have tons of enums and descriptions for all, e.g. files.encoding. We can't show all of them because the description will be very long. The enumDescriptions for files.encoding are very short, just human-readable names for the encodings. For cases like this, I propose a new setting schema property, inlineEnumDescriptions, which will cause us to, in the GUI editor, display the enumDescriptions in the dropdown along with the enum values. Example:

• The reason I won't do this for every setting is that some enumDescriptions have lots of text, and reading it in a dropdown is not a good experience. Example:

• We have to just handle these case-by-case

• Quotes/backticks

  • I think that all setting names, enum values, keyboard key names, command names, etc should be surrounded by backticks and rendered as code.

[itamark]

I prefer the documentation link idea over arbitrary links in markdown. Will make for cleaner code.
Maybe since there might be a requirement for multiple links - a user can change the text of the documentation label to say something like docs and examples or whatever else - and then put the contents they'd normally link to in the external docs.

Oh and also +10000 for showing enumDescriptions somewhere.