Code

Learn how Vale handles source code.

Vale supports linting source code comments in a number of languages (see below).

Language	Extensions	Scopes
C	.c, .h	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
C#	.cs, .csx	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
C++	.cpp, .cc, .cxx, .hpp	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
CSS	.css	/.../ (text.comment.line.ext), /* (text.comment.block.ext)
Go	.go	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
Haskell	.hs	-- (text.comment.line.ext), {- (text.comment.block.ext)
Java	.java, .bsh	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
JavaScript	.js	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
Julia	.jl	# (text.comment.line.ext), "..." (text.comment.line.ext) #= (text.comment.block.ext), """ (text.comment.block.ext)
LESS	.less	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
Lua	.lua	-- (text.comment.line.ext), --[[ (text.comment.block.ext)
Perl	.pl, .pm, .pod	# (text.comment.line.ext)
PHP	.php	// (text.comment.line.ext), # (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
PowerShell	.ps1	# (text.comment.line.ext), <#...#> (text.comment.line.ext), <# (text.comment.block.ext)
Protobuf	.proto	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
Python	.py, .py3, .pyw, .pyi, rpy	# (text.comment.line.ext), """ (text.comment.block.ext)
QML	.qml	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
R	.r, .R	# (text.comment.line.ext)
Ruby	.rb	# (text.comment.line.ext), ^=begin (text.comment.block.ext)
Rust	.rs	// (text.comment.line.ext)
Sass	.sass, .scss	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
Scala	.scala, .sbt	// (text.comment.line.ext)
Swift	.swift	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)
TypeScript	.ts, .tsx	// (text.comment.line.ext), /.../ (text.comment.line.ext), /* (text.comment.block.ext)

Associations

In many languages, it’s common for comments to contain embedded markup (e.g., Markdown, reStructuredText, etc.) within them. For example, consider the following Rust doc comment:

impl Person {
    /// Creates a person with the given name.
    ///
    /// # Examples
    ///
    /// ```
    /// // You can have rust code between fences
    /// // inside the comments If you pass --test
    /// // to `rustdoc`, it will even test it for
    /// // you!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }
}

If the embedded markup is one of the supported formats, you can associate the comment scope with a markup type. This will allow you to lint the embedded markup as if it were a standalone file.

StylesPath = styles
MinAlertLevel = suggestion

[formats]
# Rust + Markdown
rs = md

[*.{rs,md}]
BasedOnStyles = Vale

How embedded markup is linted: tree-sitter finds each comment in the source file, the per-line decoration is stripped, the remaining body is parsed as Markdown, and every alert is mapped back to its original line and column in the source.

Once a markup format has been assigned, you can make use of all the supported features of that format (such as ignore patterns and comment-based configuration) in your source code comments.

This includes TokenIgnores and BlockIgnores, which are otherwise unavailable in source code: they work by wrapping a match in the format's inline or block code delimiter, so they need a markup format to wrap it with. Associating one makes them available.

Block comment decoration

Requires Vale v3.17.0 or later. Earlier versions passed the leading asterisks through to the markup parser, which read a block comment as a single list.

Block comments in C-style languages conventionally decorate each line with a leading asterisk:

/**
 * Reads the record and returns it.
 *
 * Pass `refresh` to bypass the cache:
 *
 * * `refresh: true` re-reads from disk.
 * * `refresh: false` uses the cache.
 */

That decoration is removed before the comment is handed to the markup parser, so the body above is read as a paragraph followed by a list—not as one long list, which is what the leading asterisks would otherwise make it.

Relative indentation is preserved, so indented code blocks inside a comment still work:

/**
 * Formats the value for display.
 *
 * ```
 * const output = format(value);
 * ```
 */

The fenced block is treated as code and left alone, exactly as it would be in a standalone Markdown file.

An asterisk is only treated as decoration when whitespace or the end of the line follows it. A line beginning *emphasis* or **bold** keeps its markup.