Settings

All available setting keys (including package-defined ones) are parsed into memory, grouped by their file name. Syntax-specific settings files are recognized and all settings found for the general Preferences.sublime-settings file are valid in those.

This is then used to provide the following features.

Settings Linting

All unknown setting keys are highlighted.

The mark style is configurable in PackageDev's settings.

Settings Completions

Completions are provided for both setting keys and their default values. Additional settings are parsed from the command's comment, located above the command in the source. Also works with list settings.

Settings Popups

After completing a setting key or when hovering over a key name, a popup is shown with a description of the setting and its default value. (The description is actually the command's comment.)

Quick-Edit Icons

A handy icon is added to all keys in the side-by-side settings view. When clicking it, you are taken to the appropriate location in the user settings file to edit this setting, adding it to the file if necessary.

Providing Descriptions

A setting's description is sourced from its comment, which is expected to be above the setting's key. Comments are read from the package-provided file, not from files in the User package.

Value suggestions are recognized within double quotes or backticks.

Following is an excerpt from the Default/Preferences.sublime-settings file showing the expected format:

{
    // Set to false to turn off the indentation guides.
    // The color and width of the indent guides may be customized by editing
    // the corresponding .tmTheme file, and specifying the colors "guide",
    // "activeGuide" and "stackGuide"
    "draw_indent_guides": true,

    // Controls how the indent guides are drawn, valid options are
    // "draw_normal" and "draw_active". draw_active will draw the indent
    // guides containing the caret in a different color.
    "indent_guide_options": ["draw_normal"],
}

Providing Descriptions Without Altering Values

Because settings in .sublime-settings files are automatically read and applied by Sublime Text, you may provide a .sublime-settings-hints file within your package that describes the settings interpreted by your plugin code without altering their values. Just make sure that the base name (before the extension) matches.