> For the complete documentation index, see [llms.txt](https://docs.vale.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vale.sh/formats/code.md).

# Code

Learn how Vale handles source code.

Vale lints the comments in source code, found with a [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar for each language below. Clojure and PowerShell have no bundled grammar and are read with comment patterns instead. A one-line comment is scoped `text.comment.line` and a comment spanning lines `text.comment.block`, each followed by the file's extension.

| Language   | Extensions                                           | Scopes                                                                                                                                                                                                                                                                        |
| ---------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C          | `.c`, `.h`                                           | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Clojure    | `.clj`, `.cljs`, `.cljc`, `.cljd`                    | `;` (`text.comment.line.ext`)                                                                                                                                                                                                                                                 |
| C#         | `.cs`, `.csx`                                        | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| C++        | `.cpp`, `.cc`, `.cp`, `.cxx`, `.c++`, `.hpp`, `.h++` | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| CSS        | `.css`                                               | <p><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                                                                                  |
| Elixir     | `.ex`, `.exs`                                        | <p><code>#</code> (<code>text.comment.line.ext</code>),<br><code>@doc</code> (<code>text.comment.doc.line.ext</code>),<br><code>@moduledoc</code> (<code>text.comment.doc.block.ext</code>)</p>                                                                               |
| Go         | `.go`                                                | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Haskell    | `.hs`                                                | <p><code>--</code> (<code>text.comment.line.ext</code>),<br><code>{-</code> (<code>text.comment.block.ext</code>)</p>                                                                                                                                                         |
| Java       | `.java`, `.bsh`                                      | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| JavaScript | `.js`, `.jsx`                                        | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Julia      | `.jl`                                                | <p><code>#</code> (<code>text.comment.line.ext</code>),<br><code>#=</code> (<code>text.comment.block.ext</code>)</p>                                                                                                                                                          |
| LESS       | `.less`                                              | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Lua        | `.lua`                                               | <p><code>--</code> (<code>text.comment.line.ext</code>),<br><code>--\[\[</code> (<code>text.comment.block.ext</code>)</p>                                                                                                                                                     |
| Perl       | `.pl`, `.pm`, `.pod`                                 | `#` (`text.comment.line.ext`)                                                                                                                                                                                                                                                 |
| PHP        | `.php`                                               | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>#</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p> |
| PowerShell | `.ps1`, `.psm1`, `.psd1`                             | <p><code>#</code> (<code>text.comment.line.ext</code>),<br><code><#...#></code> (<code>text.comment.line.ext</code>),<br><code><#</code> (<code>text.comment.block.ext</code>)</p>                                                                                            |
| Protobuf   | `.proto`                                             | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Python     | `.py`, `.py3`, `.pyw`, `.rpy`, `.cpy`, `SConstruct`  | <p><code>#</code> (<code>text.comment.line.ext</code>),<br><code>"""</code> (<code>text.comment.block.ext</code>)</p>                                                                                                                                                         |
| QML        | `.qml`                                               | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| R          | `.r`, `.R`                                           | `#` (`text.comment.line.ext`)                                                                                                                                                                                                                                                 |
| Ruby       | `.rb`, `Gemfile`, `Rakefile`, `Brewfile`, `.gemspec` | <p><code>#</code> (<code>text.comment.line.ext</code>),<br><code>^=begin</code> (<code>text.comment.block.ext</code>)</p>                                                                                                                                                     |
| Rust       | `.rs`                                                | `//` (`text.comment.line.ext`)                                                                                                                                                                                                                                                |
| Sass       | `.sass`, `.scss`                                     | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Scala      | `.scala`, `.sbt`                                     | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| Swift      | `.swift`                                             | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |
| TypeScript | `.ts`, `.tsx`                                        | <p><code>//</code> (<code>text.comment.line.ext</code>),<br><code>/</code><em><code>...</code></em><code>/</code> (<code>text.comment.line.ext</code>),<br><code>/\*</code> (<code>text.comment.block.ext</code>)</p>                                                         |

## [Documentation attributes](#documentation-attributes)

{% hint style="info" %}
Requires Vale v3.19.0 or later.
{% endhint %}

Elixir has no documentation comment syntax: its published API documentation lives in module attributes holding a string or a heredoc, and that is what `mix docs` renders.

```elixir
defmodule Session do
  @moduledoc """
  A scheduled period of care delivery.
  """

  @doc "Books a session for a client."
  def book(client), do: ...
end
```

Both comments and attributes are extracted. `@moduledoc`, `@doc`, `@typedoc`, and `@shortdoc` carry a `doc` scope—`text.comment.doc.line` and `text.comment.doc.block`—so published documentation can be held to a different standard than an implementation note, or excluded on its own via [`IgnoredScopes`](/keys/ignoredscopes.md). `@doc false` and `@doc since: "1.0.0"` hold no prose, and neither is extracted.

## [Associations](#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:

````rust
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.

```ini
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.](https://2533404145-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEMH7s0sC5N9L8xSMXGwW%2Fuploads%2Fgit-blob-9bee0984cbef3083f7dcb26e94a66996ac16dfba%2Fembedded.svg?alt=media)

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`](/keys/tokenignores.md) and [`BlockIgnores`](/keys/blockignores.md), 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](#block-comment-decoration)

{% hint style="info" %}
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.
{% endhint %}

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

```javascript
/**
 * 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:

````javascript
/**
 * 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.

{% hint style="info" %}
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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vale.sh/formats/code.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.