Docblock Abstract Syntax Tree.
docast is a specification for representing docblock comments as abstract syntax trees.
It implements the unist spec.
- Introduction
- Types
- Nodes (abstract)
- Nodes
- Mixins
- Content model
- 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 @flex-development/unist-util-types @types/mdast @types/unistinterface Node extends unist.Node {
position?: Position | undefined
}Node (unist.Node) is a syntactic unit in docast syntax trees.
The position field represents the location of a node in a source document. The value of the position field implements
the Position interface. The position field must not be present if a node is generated.
interface Position {
end: Point
start: Point
}Position represents the location of a node in a source file.
The start field of Position represents the index of the first character of the parsed source region. The end
field represents the index of the first character after the parsed source region, whether it exists or not. The value
of the start and end fields implement the Point interface.
If the syntactic unit represented by a node is not present in the source file at the time of parsing, the node is said to be generated and it must not have positional information.
interface Point {
column: number // >= 1
line: number // >= 1
offset: number // >= 0
}Point represents one place in a source file.
The line and column fields are 1-indexed integers representing a line and column in a source file. The offset
field (0-indexed integer) represents a character in a source file.
The term character refers to a (UTF-16) code unit as defined by the Web IDL specification.
interface Literal extends Node {
value: string
}Literal represents an abstract interface in docast containing a value.
Its value field is a string.
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, TypeExpression>[]
| [TypeExpression, ...Exclude<BlockTagContent, TypeExpression>[]]
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 {
identifier: string
kind: number | string
parent?: CodeSegment | null | undefined
position: Position
}CodeSegment represents the code segment in a file that is documented by a comment.
The identifier field represents the name of documented code segment. The value of the identifier field is a
non-empty string that matches the identifier found in the respective programming langauge's AST.
The kind field represents the syntax kind of the code segment. The value of the kind field is an enumerated value.
The parent field represents the code segment the current segment is nested under. The value of the parent field may
be null or undefined for top-level code segments, or for nested code segments, implement the CodeSegment interface.
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'
}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 TypeExpression extends Literal {
data?: TypeExpressionData | undefined
type: 'typeExpression'
}TypeExpression (Literal) represents a type defintion or constraint.
TypeExpression can be used in block tag nodes. It cannot contain any children — it is a leaf.
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 | PhrasingContentNodes 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 | TypeExpressionBlock 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
| PhrasingContentDescription content represents description text, and its markup.
type FlowContent = BlockTag | DescriptionFlow content represents the sections of comment.
type PhrasingContent = InlineTag | mdast.Code | mdast.PhrasingContentPhrasing content represents comment text, and its markup.
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.