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
• Types
• Nodes (abstract)
  • Node
  • Literal
  • Parent
• Nodes
  • BlockTag
  • Comment
    • CodeSegment
  • Description
  • InlineTag
  • Root
  • TypeMetadata
• Mixins
  • Tag
    • TagName
• Content model
  • BlockTagContent
  • DescriptionContent
  • FlowContent
  • PhrasingContent
  • TypeExpression
• 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 TypeScript-like grammar.

docast extends unist, a format for syntax trees, to benefit from its ecosystem of utilities. It also integrates with mdast, a specification for representing markdown.

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 that supports docblock comments.

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 a setting akin to jsdoc/check-tag-names or jsdoc.structuredTags.

TypeScript users can integrate docast type definitions into their project by installing the appropriate packages:

yarn add @flex-development/docast

interface Node extends unist.Node {}

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

interface Literal extends Node {
  value: bigint | boolean | number | string | null | undefined
}

Literal represents an abstract interface in docast containing the smallest possible value.

interface Parent extends unist.Parent {
  children: Child[]
}

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

Its content is limited to docast content and mdast content.

interface BlockTag extends Parent, Tag {
  children:
    | Exclude<BlockTagContent, TypeMetadata>[]
    | [TypeMetadata, ...Exclude<BlockTagContent, TypeMetadata>[]]
  data?: BlockTagData | undefined
  type: 'blockTag'
}

BlockTag (Parent) represents top-level metadata.

Block tags should be the only element on their line, except in cases where special meaning is assigned to succeeding text. All text following a block tag name, up until the start of the next block tag name, or comment closer (*/), is considered to be the block tag's tag content.

BlockTag can be used in comment nodes. Its content model is block tag content.

interface Comment extends Parent {
  children:
    | Exclude<FlowContent, Description>[]
    | [summary: Description, ...Exclude<FlowContent, Description>[]]
  code?: CodeSegment | null | undefined
  data?: CommentData | undefined
  type: 'comment'
}

Comment (Parent) represents a docblock comment in a source file.

The code field represents the segment of code documented by a comment. The value of the code field may be null, undefined, or implement the CodeSegment interface. The code field must not be present if a comment is used only to provide additional information.

Comment can be used in root nodes. Its content model is flow content.

interface CodeSegment {
  position: unist.Position
  type: string
}

CodeSegment represents the code segment in a file that is documented by a comment.

The value of the type field is the node type of the code segment.

interface Description extends Parent {
  children: DescriptionContent[]
  data?: DescriptionData | undefined
  type: 'description'
}

Description (Parent) represents the text of a comment. It is located at the start of a comment, before any block tags, and may contain Markdown content.

Description can be used in comment nodes. Its content model is description.

interface InlineTag extends Literal, Tag {
  data?: InlineTagData | undefined
  type: 'inlineTag'
  value: string
}

InlineTag (Literal) represents inline metadata.

Inline tags are denoted by wrapping a tag name and any tag content in angle brackets ({ and }).

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

interface Root extends Parent {
  children: Comment[]
  data?: RootData | undefined
  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 TypeMetadata extends Parent {
  children: TypeExpression[]
  data?: TypeMetadataData | undefined
  raw: string
  type: 'typeMetadata'
}

TypeMetadata (Parent) represents an inlined type expression (e.g. {number}).

TypeMetadata can be used in block tag nodes. Its content model is type expresssion.

A raw field must be present. Its value is the raw type expression (e.g. number).

interface Tag {
  name: TagName
}

Tag represents metadata associated with a comment.

The name field represents the tag name. Tag names start with an at-sign (@) and may contain any ASCII letter after the at-sign.

type TagName<T extends string = string> = `@${T}`

type Content = BlockTagContent | DescriptionContent | FlowContent | PhrasingContent

Nodes are grouped by content type, if applicable. Each node in docast, with the exception of Comment, falls into one or more categories of Content.

type BlockTagContent = PhrasingContent | TypeMetadata

Block content represents block tag text, and its markup.

type DescriptionContent =
  | mdast.Blockquote
  | mdast.Definition
  | mdast.FootnoteDefinition
  | mdast.List
  | mdast.ListItem
  | mdast.Paragraph
  | mdast.Table
  | mdast.ThematicBreak
  | PhrasingContent

Description content represents description text, and its markup.

type FlowContent = BlockTag | Description

Flow content represents the sections of comment.

type PhrasingContent = InlineTag | mdast.Code | mdast.PhrasingContent

Phrasing content represents comment text, and its markup.

type TypeExpression = TypeExpressionMap[keyof TypeExpressionMap]

TypeExpression content is a type expression.

When developing type expression parsers compatible with docast, the TypeExpressionMap map should be augmented (and exported! 😉) to register custom nodes:

declare module '@flex-development/docast' {
  interface TypeExpressionMap {
    arrayType: ArrayType
    assertionPredicate: AssertionPredicate
    bigint: BigIntLiteral
    boolean: BooleanLiteral
    conditionalType: ConditionalType
    constructorType: ConstructorType
    functionType: FunctionType
    genericType: GenericType
    identifier: Identifier
    inferType: InferType
    intersectionType: IntersectionType
    nonNullableType: NonNullableType
    null: NullLiteral
    nullableType: NullableType
    number: NumberLiteral
    objectLiteralType: ObjectLiteralType
    optionalType: OptionalType
    parenthesizedType: ParenthesizedType
    propertyAccessType: PropertyAccessType
    string: StringLiteral
    super: Super
    templateLiteral: TemplateLiteral
    this: This
    tupleType: TupleType
    typeOperation: TypeOperation
    typePredicate: TypePredicate
    typeSymbol: TypeSymbol
    undefined: UndefinedLiteral
    unionType: UnionType
    variadicType: VariadicType
  }
}

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.

Any text following a block tag name (e.g. @example, @param), up until the start of the next block tag or comment closer (*/), or any text following an inline tag name, up until the closing punctuator (}).

See the unist list of utilities for more utilities.

• docast-util-from-docs - parse docblocks

See CONTRIBUTING.md.

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

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.