tree-sitter-sassdoc

A tree-sitter grammar for SassDoc documentation comments.

Overview

This parser provides syntax highlighting and structural parsing for SassDoc documentation comments in SCSS files. It's designed to be used as an injected language within tree-sitter-scss.

Supported Annotations

Annotation	Aliases	Description
@access		Access level (public or private)
@alias		Defines the item as an alias of another item
@author		Author of the documented item
@content		Documents use of @content directive in mixins
@deprecated		Marks item as deprecated with optional message
@example		Code example with optional language identifier
@group		Group the documented item belongs to
@ignore		Content to be ignored by documentation generators
@link	@source	Link to external resource with optional caption
@name		Custom name for the documented item
@output	@outputs	Output generated by a mixin
@package		Package the item belongs to (custom annotation)
@param	@parameter, @arg, @argument	Documents a parameter with type, name, default value, and description
@property	@prop	Documents map properties with dot notation for nesting
@require	@requires	Dependencies required by the documented item
@return	@returns	Documents the return value with type and description
@see		Reference to related items
@since		Version when the item was added
@throw	@throws, @exception	Exceptions that may be thrown
@todo		Tasks to be completed
@type		Documents the type of a variable

Features

• Full support for /// triple-slash comment style
• Union types: {String | Number | Bool}
• Variable references: $variable-name
• Default values: [default-value]
• Descriptions with - separator
• Group names and version numbers
• See/require references with type specifiers: {mixin}, {function}, {variable}, {placeholder}
• Property names with dot notation: base.colors.primary
• URLs with optional captions
• Language injection in @example blocks - SCSS, CSS, HTML, JavaScript, etc.

Installation

Neovim (with nvim-treesitter)

Add the parser configuration to your Neovim config:

local parser_config = require("nvim-treesitter.parsers").get_parser_configs()

parser_config.sassdoc = {
  install_info = {
    url = "https://github.com/simeonoff/tree-sitter-sassdoc",
    files = { "src/parser.c" },
    branch = "main",
  },
  filetype = "sassdoc",
}

-- Add queries to runtime path
vim.opt.runtimepath:append("/path/to/tree-sitter-sassdoc")

Then install the parser:

:TSInstall sassdoc

SCSS Injection

To enable SassDoc highlighting within SCSS files, add this injection query to your SCSS queries (~/.config/nvim/queries/scss/injections.scm):

; extends

; Inject sassdoc into /// documentation comments
((single_line_comment) @injection.content
  (#match? @injection.content "^///")
  (#set! injection.language "sassdoc"))

Example

/// Calculates the sum of two numbers.
///
/// @param {Number} $a - The first number
/// @param {Number} $b - The second number
/// @return {Number} The sum of $a and $b
/// @example scss
///   $result: sum(1, 2); // Returns 3
/// @see subtract
/// @since 1.0.0
/// @author John Doe
@function sum($a, $b) {
  @return $a + $b;
}

Syntax Tree

The above example produces a tree like:

(document
  (description)
  (tag (tag_param (type (type_name)) (variable_name) (tag_description (line_description))))
  (tag (tag_param (type (type_name)) (variable_name) (tag_description (line_description))))
  (tag (tag_return (type (type_name)) (line_description)))
  (tag (tag_example (example_language) (code_block)))
  (tag (tag_see (see_reference)))
  (tag (tag_since (version)))
  (tag (tag_author (line_description))))

Development

Building

npm install
tree-sitter generate

Testing

tree-sitter test

Testing a file

tree-sitter parse example.sassdoc

Highlight Capture Groups

The following highlight capture groups are used:

Capture	Description
@keyword	Tag names (@param, @return, etc.)
@keyword.modifier	Access modifiers (public, private)
@type	Type names and references
@variable	Variable names ($name)
@number	Version numbers
@comment	Description text and link captions
@label	Example language identifier
@string	Code blocks and custom names
@string.special	Default values
@string.special.url	URLs
@function	See/require/alias references
@module	Group and package names
@property	Property names

Text Objects

For use with nvim-treesitter-textobjects. Example keybindings:

-- In your textobjects config
textobjects = {
  select = {
    enable = true,
    keymaps = {
      ["ab"] = "@block.outer",        -- Select entire tag
      ["ib"] = "@block.inner",        -- Select code block content
      ["aa"] = "@parameter.outer",    -- Select @param/@prop tag
      ["ia"] = "@parameter.inner",    -- Select param description
      ["at"] = "@type.outer",         -- Select type annotation {Type}
      ["it"] = "@type.inner",         -- Select type name only
    },
  },
  move = {
    enable = true,
    goto_next_start = {
      ["]b"] = "@block.outer",        -- Next tag
      ["]a"] = "@parameter.outer",    -- Next @param
    },
    goto_previous_start = {
      ["[b"] = "@block.outer",        -- Previous tag
      ["[a"] = "@parameter.outer",    -- Previous @param
    },
  },
}

Available captures:

Capture	Description
@block.outer	Entire tag
@block.inner	Code block content in @example
@parameter.outer	@param or @prop tag
@parameter.inner	Parameter/property description
@return.outer	@return tag
@return.inner	Return description
@comment.outer	Description block or tag description
@comment.inner	Line description text
@type.outer	Type annotation with braces {Type}
@type.inner	Type name only
@string.outer	@link tag
@string.inner	URL only
@variable.outer	Variable name ($name)
@property.outer	Property name (base.colors.primary)
@reference.outer	@see or @require tag
@statement.outer	Individual code line in @example

Language Injection

The injections.scm query enables syntax highlighting inside @example code blocks:

/// @example scss
///   $color: blue;
///   .class { color: $color; }

Supported languages: Any language with a tree-sitter parser (scss, css, html, javascript, etc.)

License

MIT