-
Notifications
You must be signed in to change notification settings - Fork 6
Setting Descriptions
This page describes style guidelines for writing descriptions for settings.
-
description
/enumDescriptions
is rendered as plain text.markdownDescription
/markdownEnumDescriptions
is rendered as markdown. Be careful to use the correct one. If you are using links, backticks, lists, etc use the markdown property. - Commands, keycodes, code snippets, or other "data items" must be in backticks with no quotes.
- 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.
- 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
.
- Example of enum without enumDescriptions:
-
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
. -
Avoid using links in enumDescriptions, because they will not be clickable.
-
- 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#`
Project Management
- Roadmap
- Iteration Plans
- Development Process
- Issue Tracking
- Build Champion
- Release Process
- Running the Endgame
- Related Projects
Contributing
- How to Contribute
- Submitting Bugs and Suggestions
- Feedback Channels
- Source Code Organization
- Coding Guidelines
- Testing
- Dealing with Test Flakiness
- Contributor License Agreement
- Extension API Guidelines
- Accessibility Guidelines
Documentation