Sweep setting descriptions for formatting consistency

[roblourens]

Steps

• Find all the settings in your assigned section (usually in something.contribution.ts)
• Check each description and apply the rules below
• Also, check how the setting name looks in the new editor. They are formatted automatically from the camelCase key. Does it looks find, or could a different name look better if it was chosen manually?

Setting description rules

• Check that each description is accurate, grammatically correct, and clear.
• Descriptions should be understandable by non-developers or users who don't know everything about vscode.
• Don't use "we" to mean "vscode".
• Use "macOS" instead of "OS X"
• Descriptions and enumDescriptions must end in a period.
• Commands, keycodes, code snippets, or other "data items" must be in backticks with no quotes.
• Bools
  • Use "Controls whether" instead of "Controls if". (Other wordings are ok)
  • Use enabled/disabled or other language instead of true/false.
• Enums

  • Ideally, enum settings should have a description and enum values clear enough that enumDescriptions aren't needed. But if the enum values aren't self-evident, enum settings should have enumDescriptions.

    • Example of enum without enumDescriptions: editor.cursorStyle.

  • An enum setting description should not duplicate info in the enumDescriptions (enumDescriptions will be rendered next to the description in both setting editors).

    • The description shouldn't list the possible enum values.

  • If enumDescriptions is specified, the length of enumDescriptions must match the length of enum. An empty string for an enumDescription is ok, if the value is self-evident. Example:
    

  • Enum values mentioned in a description must be in backticks with no quotes.

  • Note - if an enum setting has more than 10 options, its enum descriptions will be rendered inline inside the dropdown control (or in the old settings editor, only in the suggest widget). As far as I can tell, this only affects files.encoding.

• Links
  • Settings should have a markdown-style link to documentation when relevant docs exist
  • Example:

'search.exclude': {
    type: 'object',
    description: nls.localize('exclude', "[snip] [Read more about glob patterns](https://code.visualstudio.com/docs/editor/codebasics#_advanced-search-options)."),

• Other setting references
  • All references to other settings must be written in the following special format, which is rewritten into a link by the settings editor:

`#editor.detectIndentation#`

[roblourens]

Remaining blocks:

• @JacksonKearl

php.suggest.basic
php.validate.enable
php.validate.executablePath
php.validate.run
problems.autoReveal
problems.decorations.enabled
scm.alwaysShowProviders
scm.diffDecorations
scm.diffDecorationsGutterWidth
scss.colorDecorators.enable
scss.lint.argumentsInColorFunction
scss.lint.boxModel
scss.lint.compatibleVendorPrefixes
scss.lint.duplicateProperties
scss.lint.emptyRules
scss.lint.float
scss.lint.fontFaceProperties
scss.lint.hexColorLength
scss.lint.idSelector
scss.lint.ieHack
scss.lint.important
scss.lint.importStatement
scss.lint.propertyIgnoredDueToDisplay
scss.lint.universalSelector
scss.lint.unknownProperties
scss.validate
search.exclude
search.followSymlinks
search.globalFindClipboard

• @octref

debug.toolBarLocation
diffEditor.ignoreTrimWhitespace
diffEditor.renderIndicators
editor.glyphMargin
editor.hideCursorInOverviewRuler
editor.highlightActiveIndentGuide
editor.selectionHighlight
editor.showFoldingControls
editor.showUnused
emmet.syntaxProfiles
emmet.triggerExpansionOnTab
emmet.variables
git.ignoreLimitWarning
git.ignoreMissingGitWarning
git.inputValidation
javascript.format.insertSpaceAfterConstructor
javascript.format.insertSpaceAfterFunctionKeywordForAnonymousFunctions
javascript.format.insertSpaceAfterKeywordsInControlFlowStatements
less.lint.duplicateProperties
less.lint.emptyRules
less.lint.float
npm.packageManager
npm.runSilent
npm.scriptExplorerAction
scss.lint.unknownVendorSpecificProperties
scss.lint.vendorPrefix
scss.lint.zeroUnits
workbench.editor.labelFormat
workbench.editor.openPositioning
workbench.editor.openSideBySideDirection

• @JacksonKearl

workbench.commandPalette.preserveInput
workbench.editor.closeEmptyGroups
workbench.editor.revealIfOpen
workbench.editor.showIcons
workbench.editor.showTabs
workbench.editor.swipeToNavigate
workbench.editor.tabCloseButton
workbench.editor.tabSizing
workbench.fontAliasing
workbench.iconTheme
workbench.list.multiSelectModifier
workbench.list.openMode
workbench.panel.defaultLocation
workbench.quickOpen.closeOnFocusLost
workbench.settings.enableNaturalLanguageSearch
workbench.settings.openDefaultSettings
workbench.settings.settingsSearchTocBehavior
workbench.settings.tocVisible
workbench.sideBar.location
workbench.startupEditor
workbench.statusBar.feedback.visible
workbench.statusBar.visible
workbench.tips.enabled
workbench.tree.horizontalScrolling
workbench.view.alwaysShowHeaderActions
zenMode.centerLayout
zenMode.fullScreen
zenMode.hideActivityBar

I've assigned a random block of settings to everyone. Please review the settings for the block and check off your name when finished. Thanks!

• @chrmarti

css.colorDecorators.enable
css.lint.argumentsInColorFunction
css.lint.boxModel
css.lint.compatibleVendorPrefixes
css.lint.duplicateProperties
css.lint.emptyRules
css.lint.float
css.lint.fontFaceProperties
css.lint.hexColorLength
css.lint.idSelector
css.lint.ieHack
css.lint.important
css.lint.importStatement
css.lint.propertyIgnoredDueToDisplay
css.lint.universalSelector
css.lint.unknownAtRules
css.lint.unknownProperties
css.lint.unknownVendorSpecificProperties
css.lint.vendorPrefix
css.lint.zeroUnits
css.trace.server
css.validate
debug.allowBreakpointsEverywhere
debug.enableAllHovers
debug.inlineValues
debug.internalConsoleOptions
debug.openDebug
debug.openExplorerOnEnd
debug.showInStatusBar

• @ramya-rao-a

editor.accessibilitySupport
editor.autoClosingBrackets
editor.autoIndent
editor.codeActionsOnSave
editor.codeActionsOnSaveTimeout
editor.codeLens
editor.colorDecorators
editor.cursorBlinking
editor.cursorStyle
editor.cursorWidth
editor.detectIndentation
editor.dragAndDrop
editor.emptySelectionClipboard
editor.find.autoFindInSelection
editor.find.globalFindClipboard
editor.find.seedSearchStringFromSelection
editor.folding
editor.foldingStrategy
editor.fontFamily
editor.fontLigatures
editor.fontSize
editor.fontWeight
editor.formatOnPaste
editor.formatOnSave
editor.formatOnSaveTimeout
editor.formatOnType
editor.hover.delay
editor.hover.enabled
editor.hover.sticky

• @sbatten

editor.lightbulb.enabled
editor.lineHeight
editor.lineNumbers
editor.links
editor.matchBrackets
editor.minimap.enabled
editor.minimap.maxColumn
editor.minimap.renderCharacters
editor.minimap.showSlider
editor.minimap.side
editor.mouseWheelScrollSensitivity
editor.mouseWheelZoom
editor.multiCursorMergeOverlapping
editor.multiCursorModifier
editor.occurrencesHighlight
editor.overviewRulerBorder
editor.overviewRulerLanes
editor.parameterHints
editor.quickSuggestions
editor.quickSuggestionsDelay
editor.renderControlCharacters
editor.renderIndentGuides
editor.renderLineHighlight
editor.renderWhitespace
editor.roundedSelection
editor.rulers
editor.scrollBeyondLastColumn
editor.scrollBeyondLastLine
editor.selectionClipboard

• @mjbvz

editor.suggest.filterGraceful
editor.suggestFontSize
editor.suggestLineHeight
editor.suggestOnTriggerCharacters
editor.suggestSelection
editor.tabCompletion
editor.tabSize
editor.tokenColorCustomizations
editor.trimAutoWhitespace
editor.useTabStops
editor.wordBasedSuggestions
editor.wordSeparators
editor.wordWrap
editor.wordWrapColumn
editor.wrappingIndent
emmet.excludeLanguages
emmet.extensionsPath
emmet.includeLanguages
emmet.optimizeStylesheetParsing
emmet.preferences
emmet.showAbbreviationSuggestions
emmet.showExpandedAbbreviation
emmet.showSuggestionsAsSnippets
explorer.autoReveal
explorer.confirmDelete
explorer.confirmDragAndDrop
explorer.decorations.badges
explorer.decorations.colors
explorer.enableDragAndDrop

• @RMacfarlane

extensions.closeExtensionDetailsOnViewChange
extensions.ignoreRecommendations
extensions.showRecommendationsOnlyOnDemand
files.associations
files.autoGuessEncoding
files.autoSave
files.autoSaveDelay
files.defaultLanguage
files.encoding
files.eol
files.exclude
files.hotExit
files.insertFinalNewline
files.maxMemoryForLargeFilesMB
files.trimFinalNewlines
files.trimTrailingWhitespace
files.useExperimentalFileWatcher
files.watcherExclude
git.autofetch
git.autorefresh
git.autoRepositoryDetection
git.checkoutType
git.confirmSync
git.countBadge
git.decorations.enabled
git.defaultCloneDirectory
git.detectSubmodules
git.detectSubmodulesLimit
git.enableCommitSigning
git.enabled
git.enableSmartCommit
git.ignoreLegacyWarning

• @JacksonKearl

git.path
git.promptToSaveFilesBeforeCommit
git.showInlineOpenFileAction
grunt.autoDetect
gulp.autoDetect
html.autoClosingTags
html.format.contentUnformatted
html.format.enable
html.format.endWithNewline
html.format.extraLiners
html.format.indentHandlebars
html.format.indentInnerHtml
html.format.maxPreserveNewLines
html.format.preserveNewLines
html.format.unformatted
html.format.wrapAttributes
html.format.wrapLineLength
html.suggest.angular1
html.suggest.html5
html.suggest.ionic
html.trace.server
html.validate.scripts
html.validate.styles
http.proxy
http.proxyAuthorization
http.proxyStrictSSL
jake.autoDetect
javascript.format.enable
javascript.format.insertSpaceAfterCommaDelimiter

• @aeschli

javascript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis
javascript.format.insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces
javascript.format.insertSpaceAfterSemicolonInForStatements
javascript.format.insertSpaceBeforeAndAfterBinaryOperators
javascript.format.insertSpaceBeforeFunctionParenthesis
javascript.format.placeOpenBraceOnNewLineForControlBlocks
javascript.format.placeOpenBraceOnNewLineForFunctions
javascript.implicitProjectConfig.checkJs
javascript.implicitProjectConfig.experimentalDecorators
javascript.nameSuggestions
javascript.preferences.importModuleSpecifier
javascript.preferences.quoteStyle
javascript.referencesCodeLens.enabled
javascript.showUnused
javascript.suggestionActions.enabled
javascript.updateImportsOnFileMove.enabled
javascript.validate.enable
jsDocCompletion.enabled
json.colorDecorators.enable
json.format.enable
json.schemas
json.trace.server
keyboard.dispatch
keyboard.touchbar.enabled
launch
less.colorDecorators.enable
less.lint.argumentsInColorFunction
less.lint.boxModel
less.lint.compatibleVendorPrefixes

• @alexandrudima

less.lint.ieHack
less.lint.important
less.lint.importStatement
less.lint.propertyIgnoredDueToDisplay
less.lint.universalSelector
less.lint.unknownProperties
less.lint.unknownVendorSpecificProperties
less.lint.vendorPrefix
less.lint.zeroUnits
less.validate
markdown.preview.breaks
markdown.preview.doubleClickToSwitchToEditor
markdown.preview.fontFamily
markdown.preview.fontSize
markdown.preview.lineHeight
markdown.preview.linkify
markdown.preview.markEditorSelection
markdown.preview.scrollEditorWithPreview
markdown.preview.scrollPreviewWithEditor
markdown.preview.scrollPreviewWithEditorSelection
markdown.previewFrontMatter
markdown.styles
markdown.trace
merge-conflict.codeLens.enabled
merge-conflict.decorators.enabled
npm.autoDetect
npm.enableScriptExplorer
npm.exclude
outline.icons

• @isidorn

search.useIgnoreFiles
search.useRipgrep
searchRipgrep.enable
telemetry.enableCrashReporter
telemetry.enableTelemetry
typescript.autoImportSuggestions.enabled
typescript.check.npmIsInstalled
typescript.disableAutomaticTypeAcquisition
typescript.format.enable
typescript.format.insertSpaceAfterCommaDelimiter
typescript.format.insertSpaceAfterConstructor
typescript.format.insertSpaceAfterFunctionKeywordForAnonymousFunctions
typescript.format.insertSpaceAfterKeywordsInControlFlowStatements
typescript.format.insertSpaceAfterOpeningAndBeforeClosingJsxExpressionBraces
typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces
typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets
typescript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis
typescript.format.insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces
typescript.format.insertSpaceAfterSemicolonInForStatements
typescript.format.insertSpaceAfterTypeAssertion
typescript.format.insertSpaceBeforeAndAfterBinaryOperators
typescript.format.insertSpaceBeforeFunctionParenthesis
typescript.format.placeOpenBraceOnNewLineForControlBlocks
typescript.format.placeOpenBraceOnNewLineForFunctions
typescript.implementationsCodeLens.enabled
typescript.locale
typescript.npm
typescript.preferences.importModuleSpecifier
typescript.preferences.quoteStyle
typescript.quickSuggestionsForPaths
typescript.referencesCodeLens.enabled
typescript.reportStyleChecksAsWarnings
window.openFilesInNewWindow
window.openFoldersInNewWindow
window.openWithoutArgumentsInNewWindow

• @dbaeumer

typescript.tsdk
typescript.tsserver.log
typescript.tsserver.pluginPaths
typescript.tsserver.trace
typescript.updateImportsOnFileMove.enabled
typescript.useCodeSnippetsOnMethodSuggest
typescript.validate.enable
update.channel
update.enableWindowsBackgroundUpdates
update.showReleaseNotes
window.autoDetectHighContrast
window.clickThroughInactive
window.closeWhenEmpty
window.enableMenuBarMnemonics
window.menuBarVisibility
window.nativeTabs
window.newWindowDimensions
window.restoreFullscreen
window.restoreWindows
window.smoothScrollingWorkaround
window.title
window.titleBarStyle
window.zoomLevel
workbench.activityBar.visible
workbench.colorCustomizations
workbench.colorTheme
workbench.commandPalette.history

• @roblourens

diffEditor.renderSideBySide
editor.acceptSuggestionOnCommitCharacter
editor.acceptSuggestionOnEnter
editor.insertSpaces
editor.largeFileOptimizations
editor.letterSpacing
editor.smoothScrolling
editor.snippetSuggestions
editor.stablePeek
explorer.openEditors.visible
explorer.sortOrder
extensions.autoUpdate
javascript.format.insertSpaceAfterOpeningAndBeforeClosingJsxExpressionBraces
javascript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces
javascript.format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets
less.lint.fontFaceProperties
less.lint.hexColorLength
less.lint.idSelector
outline.problems.badges
outline.problems.colors
outline.problems.enabled
search.location
search.quickOpen.includeSymbols
search.smartCase
typescript.showUnused
typescript.suggestionActions.enabled
typescript.tsc.autoDetect
workbench.editor.closeOnFileDelete
workbench.editor.enablePreview
workbench.editor.enablePreviewFromQuickOpen
zenMode.hideStatusBar
zenMode.hideTabs
zenMode.restore

[dbaeumer]

@roblourens please reassign my block to someone else since I am on vacation form 8/25/2018. I can do it when I am back from vacation if it can wait some time.

[eamodio]

@roblourens should the #editor.detectIndentation# format be working? I see that it generates a link (though the title/tooltip of the link isn't so friendly) and clicking on it seems to just close the expanded setting, rather than jump to the setting referenced

[roblourens]

Yes, does it not work for you?

[eamodio]

Yes and no. So as long as there is no search (filter) then the link works fine, but if you search, then the links just close the expanded setting -- even if the linked setting also meets the search criteria

[roblourens]

Good catch. I filed #55179

[alexdima]

@roblourens How can I improve the label for a setting?

css.lint.ieHack does not look good: it gets rendered as "Lint: Ie Hack". How can I define a new Settings UI label in the package.json? i.e. in here:

          "css.lint.ieHack": {
            "type": "string",
            "scope": "resource",
            "enum": [
              "ignore",
              "warning",
              "error"
            ],
            "default": "ignore",
            "description": "%css.lint.ieHack.desc%"
          },

Edit: Another example is markdown.preview.breaks which I think would read better as "Markdown Preview: Breaks" than the current "Markdown.Preview: Breaks".

[chrmarti]

Need manual title:

• css.lint.argumentsInColorFunction
• css.lint.idSelector
• css.lint.ieHack
• debug.internalConsoleOptions
• debug.openExplorerOnEnd

[isidorn]

Need manual title:

• typescript.autoImportSuggestions.enabled
• typescript.check.npmIsInstalled
• typescript.implementationsCodeLens.enabled

[aeschli]

• JavaScript settings should be in their own category (currently in the TypeScript category)
• JavaScript titles should use JavaScript (not Javascript) -> manual title needed
• The JavaScript formatter settings description just repeat what the title says, lots of text not adding any clarity
  
• Some descriptions are cut off, but no ... visible to know that there's more to read
• JSDoc completion need manual title
  

[isidorn]

Typescript formatter settings are also very cryptic too me. Too many and repeating the title.

[roblourens]

I'm not convinced that any of these need manual titles. I want to avoid that if at all possible because I think having two names for every setting would be even more confusing than this already is, and I think we can still make the autogenerated names look nicer. @sbatten and I talked about this quite a bit on Friday too.

"Ie hack"/"IE hack" I think it would be better to have a list of known acronyms that can be formatted correctly

"Markdown.Preview: Breaks" - Settings are displayed in two ways, either in context under their section, "Markdown", or without context in a list of search results. In context where the section title is the same as the first setting component, the first component isn't shown. There's a bug with this in the extension section, but this should be shown as "Preview: Breaks" under the "Markdown" section, which I think is good.

But then when the setting is shown in a list of search results, its label needs to include the full context, so "Markdown" must be included. I think "Markdown.Preview:" shows that there is this hierarchy of the "Preview" feature under the "Markdown" section. The display could be nicer, e.g. "Markdown > Preview:". But still, you should only see the context that's needed.

@chrmarti I'm not sure what's wrong with those setting names - if the key itself isn't clear, I think we should fix that by having a good description or changing the setting entirely. But I think adding a new name for the same setting will cause issues.

@isidorn I'm also not sure what name you would like to use. Fixing the duplication of typescript will help. @sbatten and I discussed special-casing '.enabled' settings so that in this case they would read like Auto Import Suggestions Enabled instead of Auto Import Suggestions: Enabled, maybe that helps.

@aeschli Yes I'd like to give extensions a way to define subcategories, like we have for builtin settings. re: JavaScript if the key is camelcased, the should is have been javaScript.*? We could fix this and "JS" similarly to "IE" with well-known formats. I'm working on either a ... or showing more of the description.

I'm not sure what to do about the format settings. I think it's an issue beyond the settings GUI. Maybe all the descriptions are simply redundant. Of course it would be cool to have a special control that shows you a preview of what those settings do, or something like that.

[JacksonKearl]

"scss.colorDecorators.enable" seems to have been removed from code

[JacksonKearl]

As has "search.globalFindClipboard"

[roblourens]

https://github.com/Microsoft/vscode/blob/master/extensions/css-language-features/package.json#L281 and https://github.com/Microsoft/vscode/blob/master/src/vs/workbench/parts/search/electron-browser/search.contribution.ts#L612

[JacksonKearl]

Well they don't show up in the search

[roblourens]

Thanks everyone for the help!

re: the conversation above, I'm happy to continue the discussion in another issue if anyone wants to.

[roblourens]

If you added a setting within the past couple weeks, please check that it also fits the guidelines, it might not be included in the list above.

[aeschli]

@JacksonKearl the colorDecorator settings are marked as deprecated and are therefore hidden (e.g. don't show up in the code completion for the settings.json). The Settings UI should still show them when set. I created #55646