Comments¶
Overview¶
Sublime Text provides a default command to comment and uncomment lines of code. This command can be enabled for any type of file using metadata files.
File Format¶
Comment markers are defined using metadata files. However, because metadata for comment markers is commonly required by packages, it’s discussed separately in this page for convenience.
Just as regular metadata files,
comment metadata files
have the .tmPreferences
extension
and use the Property List format.
The file name is ignored by Sublime Text.
See also
- Metadata Files
- Detailed documentation on metadata.
Example¶
Let’s see a basic example of a comment metadata file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>name</key>
<string>Miscellaneous</string>
<key>scope</key>
<string>source.python</string>
<key>settings</key>
<dict>
<string></string>
<key>shellVariables</key>
<array>
<dict>
<key>name</key>
<string>TM_COMMENT_START</string>
<key>value</key>
<string># </string>
</dict>
</array>
</dict>
</dict>
</plist>
In the example we’ve highlighted some parts that are specific to comment metadata files.
Structure of a Comment Metadata File¶
All comment metadata files share the same topmost structure, which is inherited from Property List format:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
...
</dict>
</plist>
These are all the valid elements in a comment metadata file:
name
Optional. Name of the metadata. Ignored by Sublime Text.
<key>name</key> <string>Shell Variables</string>
scope
Required. Comma-separated list of scope selectors to determine in which context the metadata should be active.
In most cases you’ll use the base scope for a particular syntax.
<key>scope</key> <string>source.python</string>
settings
Required. A container for settings.
<key>settings</key> <dict> ... </dict>
uuid
Optional. A unique identifier for the file. Ignored by Sublime Text.
<key>uuid</key> <string>BC062860-3346-4D3B-8421-C5543F83D11F</string>
settings
Subelements¶
shellVariables
Required. Container for comment markers.
<key>shellVariables</key> <array> ... </array>
shellVariables
Subelements¶
Note
The shellVariables
array
may contain any arbitrary subelement,
but here we’re only concerned
with those related to comments.
See Shell Variables (Child of settings) for details.
TM_COMMENT_START
Defines a default comment marker.
To define additional comment markers, name them
TM_COMMENT_START_2
,TM_COMMENT_START_3
, etc.<dict> <key>name</key> <string>TM_COMMENT_START</string> <key>value</key> <string># </string> </dict>
TM_COMMENT_END
Optional. Defines an end comment marker. If omitted,
TM_COMMENT_START
will be treated as a line comment marker.If present and a corresponding start comment marker can be found, the pair is treated as block comment markers.
To define additional end comment markers, name them
TM_COMMENT_END_2
,TM_COMMENT_END_3
, etc.<dict> <key>name</key> <string>TM_COMMENT_END_2</string> <key>value</key> <string>*/</string> </dict>
TM_COMMENT_DISABLE_INDENT
Optional. Valid values are
yes
andno
. Disables indentation for theTM_COMMENT_START
marker.To target other group of markers, use
TM_COMMENT_DISABLE_INDENT_2
, etc.<dict> <key>name</key> <string>TM_COMMENT_DISABLE_INDENT</string> <key>value</key> <string>yes</string> </dict>
Example¶
Here’s a more complete example of a comment metadata file using some of the features just discussed:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>shellVariables</key>
<array>
<dict>
<key>name</key>
<string>TM_COMMENT_START</string>
<key>value</key>
<string>// </string>
</dict>
<dict>
<key>name</key>
<string>TM_COMMENT_START_2</string>
<key>value</key>
<string>/*</string>
</dict>
<dict>
<key>name</key>
<string>TM_COMMENT_END_2</string>
<key>value</key>
<string>*/</string>
</dict>
</array>
</dict>
<key>uuid</key>
<string>BC062860-3346-4D3B-8421-C5543F83D11F</string>
</dict>
</plist>