Better documentation for individual settings

[jabacchetta]

New VSCode users typically end up frustrated trying to get the editor to behave as they'd expect it to. A lot of times there is just a misunderstanding as to what the consequences might be when a setting is modified from its default state.

One way to improve this situation is to add more comprehensive descriptions to settings (even if it's a hidden description that needs to be expanded with a "more" button).

It also doesn't help that custom descriptions (via comments) currently have their own limitations.

Below is an example of what my own comments look like for just a few of the settings in my settings.json file. This is a good snapshot of the problem that new users are facing.

{
  // Tab always completes a selected quick suggestion, regardless of what this setting is set to.
  // This setting comes into play only when the quick suggestion widget is not being displayed. If
  // set to `onlySnippets`, cursor must be at the end of an exact-match snippet prefix to tab
  // complete. If set to `on`, it will cycle through all suggestions, including snippets (even if it
  // isn't an exact-match). As it relates to all suggestions, this feature is most useful for
  // continuing to tab through a list of suggestions, even after the quick suggestion widget has
  // closed (e.g. accidentally accepted the wrong suggestion). A "blind" tab (before the quick
  // suggestion widget has even had a chance to open) only makes sense when suggestion is known
  // (e.g. exact-match snippet prefix). And this comes in handy because we can complete snippets
  // faster (no need to wait for quick suggestions to appear before pressing tab). Note that with
  // this set to on, emmet abbreviation expansion will not work in most cases unless its keyboard
  // shortcut is reassigned, because there will almost always be a suggestion list to cycle through.
  // With this settting set to `onlySnippets`, the conflict isn't as noticeable, since, again,
  // snippets need an exact match prefix to expand. Therefore, as long as custom snippet prefixes
  // are strategically selected to not conflict with common/likely emmet abbreviations, there won't
  // be an issue. I prefer this set to `onlySnippets`, not for the limited cycling benefit, but for
  // the faster snippet completion.
  "editor.tabCompletion": "onlySnippets",

 // Setting `snippetSuggestions` to `top` allows you to keep quick suggestions on, while also
  // guaranteeing that you can enter a snippet prefix and immediately tab complete it. In other
  // words, if quick suggestions appear before you've had a chance to tab, that snippet will be the
  // first suggestion (as opposed to some local variable, for example), so tab will still insert the
  // snippet. With this set to `top`, snippet prefixes should be kept short (3 characters or less),
  // so that auto completing other useful suggestions like local variables does not require typing
  // more than 4 characters.
  "editor.snippetSuggestions": "top",

 // This only applies when quick suggestions are not active. Tab always completes quick
  // suggestions, regardless of whether or not it's an Emmet abbreviation. Setting this to `true` is
  // required for expanding / auto completing React components. Note that if setting this to `true`,
  // Emmet will expand all words as custom tags when quick suggestions is not active (not just React
  // component names). This does not appear to negatively affect having `editor.tabCompletion` set
  // to `onlySnippets`. In other words, snippet expansion and Emmet abbreviation expansion appear to
  // correctly take precedence over each other according to context.
  "emmet.triggerExpansionOnTab": true,

  // Emmet works with .jsx files out of the box. If using React with .js files, setting
  // "javascript": "javascriptreact" is required for consistent tab expansion, and for Emmet
  // abbreviation suggestions (e.g. getting `div` suggestion after typing `di`).
  "emmet.includeLanguages": {
    "javascript": "javascriptreact"
  },
}

[roblourens]

@ramya-rao-a I removed you from the auto-assign bot

@jabacchetta Much of this seems specific to your use cases and your workflow and preferences. We try to explain what the settings do, and some of that is in the description for an individual enum value, but I'm not going to explain "why" you should use a setting, or how to use it with specific technologies like React.

[jabacchetta]

Yeah, I was really only presenting my comments as a snapshot of how users could easily become confused on what the consequences of changing a setting would be.

Focusing on the first setting (non-opinionated, not tech-specific), editor.tabCompletion for example, I think the comment explains exactly what most users probably wouldn't be aware of.

There's a lot of synergy happening between different settings, and the advantages/disadvantages to the different options usually aren't clear until you've either stumbled across them or spent a lot of time experimenting with them.

Whether this information is added to the descriptions in the editor, in the documentation, or somewhere else, it would without a doubt be helpful to new users.

Of course, feel free to close this issue if you disagree. At this point, I've already personally spent the many hours necessary to figure it all out, and am just throwing the idea out there as a way to potentially smooth over the transition to VSCode for others.