Docblock Abstract Syntax Tree.

docast is a specification for representing docblock comments as abstract syntax trees.

It implements the unist spec.

• Introduction
  • Where this specification fits
• Nodes
  • Node
  • Parent
  • Root
  • Comment
  • ImplicitDescription
  • BlockTag
  • InlineTag
• Interfaces
  • Context
• Glossary
• List of utilities
• Contribute

This document defines a format for representing docblock comments as abstract syntax trees. Development of docast started in October 2022. This specification is written in a Web IDL-like grammar.

docast extends unist, a format for syntax trees, to benefit from its ecosystem of utilities.

docast relates to JavaScript and TypeScript in that both languages support docblock comments. docast is language-agnostic, however, and can be used with any programming language.

docast relates to JSDoc, TSDoc, and typedoc in that these tools parse docblock comments. These tools also have a limited set of tags that developers are allowed to use. If developers already have a set of tags they're using, they must spend additional time re-configuring those tags for their chosen tool. docast does not enforce any tag semantics — the user does. Tag specifications can be left to an ESLint rule or setting akin to jsdoc/check-tag-names or jsdoc.structuredTags.

interface Node <: UnistNode {
  type: 'block-tag' | 'comment' | 'implicit-description' | 'inline-tag' | 'root'
}

Node (UnistNode) is a syntactic unit in docast syntax trees.

interface Parent <: UnistParent {
  children: [BlockTag | Comment | ImplicitDescription | InlineTag]
  type: 'block-tag' | 'comment' | 'implicit-description' | 'root'
}

Parent (UnistParent) represents an abstract interface in docast containing other nodes (said to be children).

interface Root <: Parent {
  children: [Comment]
  type: 'root'
}

Root (Parent) represents a document.

Root can be used as the root of a tree, never as a child. It can contain comment nodes.

interface Comment <: Parent {
  children: [BlockTag | ImplicitDescription]
  context: Context?
  type: 'comment'
  value: string
}

Comment (Parent) represents a docblock comment.

Comment can be used in root nodes. It can contain implicit description and block tag nodes.

A comment has context if positioned exactly one line before the code it documents.

interface ImplicitDescription <: Parent {
  children: [InlineTag]
  type: 'implicit-description'
  value: string
}

ImplicitDescription (Parent) represents a piece of text located at the beginning of a docblock comment.

ImplicitDescription can be used in comment nodes. It can contain inline tag nodes.

interface BlockTag <: Parent {
  children: [InlineTag]
  tag: string
  text: string
  type: 'block-tag'
  value: string
}

BlockTag (Parent) represents metadata in a docblock comment.

BlockTag can be used in comment nodes. It can contain inline tag nodes.

interface InlineTag <: Node {
  tag: string
  text: string
  type: 'inline-tag'
  value: string
}

InlineTag (Node) represents inline metadata in a docblock comment.

InlineTag can be used in implicit description and block tag nodes. It cannot contain any children — it is a leaf.

interface Context {
  identifier: string
  kind: string
  parent: string?
  position: UnistPosition
}

Data representing the segment of code a comment documents.

See the unist glossary for more terms.

A specially formatted comment in a source file used to document a segment of code or provide additional information.

See the unist list of utilities for more utilities.

• docast-parse — unified compliant file parser

See CONTRIBUTING.md.

Ideas for new utilities and tools can be posted in docast/ideas.