TypeScript icon, indicating that this package has built-in type declarations

1.0.0-alpha.12 • Public • Published


npm module type: esm license conventional commits typescript vitest yarn

Docblock Abstract Syntax Tree.

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

It implements the unist spec.



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.

Where this specification fits

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.

Docblock comment

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

List of utilities

See the unist list of utilities for more utilities.



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


npm i @flex-development/docast

DownloadsWeekly Downloads






Unpacked Size

40.9 kB

Total Files


Last publish


  • unicornware