@goast/typescript 0.9.0 → 0.9.1

package/dist/src/ast/nodes/class.js

@@ -5,16 +5,62 @@ import { writeTsNode, writeTsNodes } from '../utils/write-ts-nodes.js';
 import { tsDecorator } from './decorator.js';
 import { tsDoc } from './doc.js';
 import { tsGenericParameter } from './generic-parameter.js';
+/**
+ * Represents a TypeScript class declaration.
+ *
+ * Written in this order: doc comment, decorators, modifiers, name, generics, heritage clauses, then the body.
+ *
+ * @template TBuilder The type of the source builder the class is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsClass
+ */
 export class TsClass extends TsNode {
+    /**
+     * The doc comment written above the class, or `null` to omit it.
+     * Descriptions of generic parameters are merged into it as `@template` tags.
+     */
     doc;
+    /**
+     * The decorators written above the class declaration, each on its own line.
+     */
     decorators;
+    /**
+     * Whether the class is written with the `export` keyword.
+     * @default false
+     */
     export;
+    /**
+     * Whether the class is written with the `abstract` modifier, placed after `export` when both are set.
+     * @default false
+     */
     abstract;
+    /**
+     * The class name, written verbatim after the `class` keyword.
+     */
     name;
+    /**
+     * The type parameters written in angle brackets after the name, such as `<T, U>`.
+     * Plain strings are written as-is; described parameters also add a `@template` tag to the doc comment.
+     */
     generics;
+    /**
+     * The base class written after `extends`, or `null` to omit the clause.
+     */
     extends;
+    /**
+     * The interfaces written after `implements` as a comma-separated list. The clause is omitted when empty.
+     */
     implements;
+    /**
+     * The members written in the class body, in the given order.
+     * Properties and bodyless methods without a doc comment or decorators are written without blank lines,
+     * other members are set off by blank lines.
+     */
     members;
+    /**
+     * Initializes a new instance of the TsClass class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.doc = options.doc ?? null;
@@ -69,6 +115,33 @@ export class TsClass extends TsNode {
     }
 }
 const createClass = (name, options) => new TsClass({ ...options, name });
+/**
+ * Factory for creating class nodes. The `write` function writes one or more class nodes to a builder.
+ *
+ * @param name The name of the class.
+ * @param options The settings of the class. See `TsClass` for the available properties.
+ * @example
+ * ```ts
+ * tsClass('X', {
+ *   decorators: [tsDecorator('decorator')],
+ *   export: true,
+ *   abstract: true,
+ *   generics: ['T', 'U'],
+ *   extends: tsReference('Y'),
+ *   implements: [tsReference('Z')],
+ *   members: [tsProperty('x'), tsConstructor(), tsMethod('y')],
+ * });
+ * // Emits:
+ * // @decorator
+ * // export abstract class X<T, U> extends Y implements Z {
+ * //   x;
+ * //
+ * //   constructor() {}
+ * //
+ * //   y();
+ * // }
+ * ```
+ */
 export const tsClass = Object.assign(createClass, {
     write: writeTsNodes,
 });

package/dist/src/ast/nodes/constructor-parameter.d.ts

@@ -7,13 +7,50 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     accessModifier?: Nullable<TsAccessModifier>;
     readonly?: Nullable<boolean>;
 }>;
+/**
+ * Represents a parameter of a constructor. Besides the properties of `TsParameter`, it can declare a class property by
+ * setting an access modifier and the `readonly` keyword.
+ *
+ * Written in this order: the decorators, the access modifier, the `readonly` keyword, the name, the optional marker,
+ * the type, then the default value. The description is not written on the parameter. The constructor adds it as a
+ * `@param` tag to its doc comment instead.
+ *
+ * @template TBuilder The type of the source builder the constructor parameter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsConstructorParameter
+ */
 export declare class TsConstructorParameter<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsParameter<TBuilder, TInjects | Injects> {
+    /**
+     * The access modifier written before the name, such as `public`. Setting one makes the parameter a class property.
+     * Nothing is written when `null`.
+     */
     accessModifier: TsAccessModifier | null;
+    /**
+     * Whether the parameter is written with the `readonly` keyword, placed after the access modifier.
+     * @default false
+     */
     readonly: boolean;
+    /**
+     * Initializes a new instance of the TsConstructorParameter class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createConstructorParameter: <TBuilder extends SourceBuilder>(name: Options<TBuilder>['name'], options?: Prettify<Omit<Options<TBuilder>, 'name'>>) => TsConstructorParameter<TBuilder>;
+/**
+ * Factory for creating constructor parameter nodes. The `write` function writes the parameters of a constructor to a
+ * builder, enclosed in parentheses.
+ *
+ * @param name The name of the parameter.
+ * @param options The settings of the parameter. See `TsConstructorParameter` for the available properties.
+ * @example
+ * ```ts
+ * tsConstructorParameter('name', { accessModifier: 'private', readonly: true, type: 'string' });
+ * // Emits:
+ * // private readonly name: string
+ * ```
+ */
 export declare const tsConstructorParameter: typeof createConstructorParameter & {
     write: typeof writeTsParameters;
 };

package/dist/src/ast/nodes/constructor-parameter.js

@@ -2,9 +2,33 @@ import { writeTsNode } from '../utils/write-ts-nodes.js';
 import { writeTsParameters } from '../utils/write-ts-parameters.js';
 import { tsDecorator } from './decorator.js';
 import { TsParameter } from './parameter.js';
+/**
+ * Represents a parameter of a constructor. Besides the properties of `TsParameter`, it can declare a class property by
+ * setting an access modifier and the `readonly` keyword.
+ *
+ * Written in this order: the decorators, the access modifier, the `readonly` keyword, the name, the optional marker,
+ * the type, then the default value. The description is not written on the parameter. The constructor adds it as a
+ * `@param` tag to its doc comment instead.
+ *
+ * @template TBuilder The type of the source builder the constructor parameter is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsConstructorParameter
+ */
 export class TsConstructorParameter extends TsParameter {
+    /**
+     * The access modifier written before the name, such as `public`. Setting one makes the parameter a class property.
+     * Nothing is written when `null`.
+     */
     accessModifier;
+    /**
+     * Whether the parameter is written with the `readonly` keyword, placed after the access modifier.
+     * @default false
+     */
     readonly;
+    /**
+     * Initializes a new instance of the TsConstructorParameter class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.accessModifier = options.accessModifier ?? null;
@@ -38,6 +62,19 @@ export class TsConstructorParameter extends TsParameter {
     }
 }
 const createConstructorParameter = (name, options) => new TsConstructorParameter({ ...options, name });
+/**
+ * Factory for creating constructor parameter nodes. The `write` function writes the parameters of a constructor to a
+ * builder, enclosed in parentheses.
+ *
+ * @param name The name of the parameter.
+ * @param options The settings of the parameter. See `TsConstructorParameter` for the available properties.
+ * @example
+ * ```ts
+ * tsConstructorParameter('name', { accessModifier: 'private', readonly: true, type: 'string' });
+ * // Emits:
+ * // private readonly name: string
+ * ```
+ */
 export const tsConstructorParameter = Object.assign(createConstructorParameter, {
     write: writeTsParameters,
 });

package/dist/src/ast/nodes/constructor.d.ts

@@ -11,15 +11,59 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     parameters?: Nullable<Nullable<TsConstructorParameter<TBuilder> | BasicAppendValue<TBuilder>>[]>;
     body?: Nullable<AppendValue<TBuilder>>;
 }>;
+/**
+ * Represents the constructor of a class.
+ *
+ * Written in this order: the doc comment, the decorators, the `constructor` keyword, the parameters in parentheses, a
+ * space, then the body in braces, followed by a line break.
+ *
+ * @template TBuilder The type of the source builder the constructor is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsConstructor
+ */
 export declare class TsConstructor<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The doc comment written above the constructor, or `null` to omit it. The descriptions of the parameters are added
+     * to it as `@param` tags, which also creates a doc comment when none is set.
+     */
     doc: TsDoc<TBuilder> | null;
+    /**
+     * The decorators written above the constructor, each on its own line.
+     */
     decorators: TsDecorator<TBuilder>[];
+    /**
+     * The parameters written in parentheses. They are written one per line when there are more than two, or when one of
+     * them has decorators.
+     */
     parameters: (TsConstructorParameter<TBuilder> | BasicAppendValue<TBuilder>)[];
+    /**
+     * The statements written in the body, on their own indented lines, or `null` to write empty braces `{}`.
+     */
     body: AppendValue<TBuilder> | null;
+    /**
+     * Initializes a new instance of the TsConstructor class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
 declare const createConstructor: <TBuilder extends SourceBuilder>(options?: Options<TBuilder>) => TsConstructor<TBuilder>;
+/**
+ * Factory for creating constructor nodes. The `write` function writes one or more constructors to a builder.
+ *
+ * @param options The settings of the constructor. See `TsConstructor` for the available properties.
+ * @example
+ * ```ts
+ * tsConstructor({
+ *   parameters: [tsConstructorParameter('x', { type: 'number' }), 'y'],
+ *   body: 'this.x = x;',
+ * });
+ * // Emits:
+ * // constructor(x: number, y) {
+ * //   this.x = x;
+ * // }
+ * ```
+ */
 export declare const tsConstructor: typeof createConstructor & {
     write: typeof writeTsNodes;
 };

package/dist/src/ast/nodes/constructor.js

@@ -4,11 +4,39 @@ import { writeTsNodes } from '../utils/write-ts-nodes.js';
 import { tsDecorator } from './decorator.js';
 import { tsDoc } from './doc.js';
 import { tsParameter } from './parameter.js';
+/**
+ * Represents the constructor of a class.
+ *
+ * Written in this order: the doc comment, the decorators, the `constructor` keyword, the parameters in parentheses, a
+ * space, then the body in braces, followed by a line break.
+ *
+ * @template TBuilder The type of the source builder the constructor is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsConstructor
+ */
 export class TsConstructor extends TsNode {
+    /**
+     * The doc comment written above the constructor, or `null` to omit it. The descriptions of the parameters are added
+     * to it as `@param` tags, which also creates a doc comment when none is set.
+     */
     doc;
+    /**
+     * The decorators written above the constructor, each on its own line.
+     */
     decorators;
+    /**
+     * The parameters written in parentheses. They are written one per line when there are more than two, or when one of
+     * them has decorators.
+     */
     parameters;
+    /**
+     * The statements written in the body, on their own indented lines, or `null` to write empty braces `{}`.
+     */
     body;
+    /**
+     * Initializes a new instance of the TsConstructor class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.doc = options.doc ?? null;
@@ -35,6 +63,22 @@ export class TsConstructor extends TsNode {
     }
 }
 const createConstructor = (options) => new TsConstructor(options ?? {});
+/**
+ * Factory for creating constructor nodes. The `write` function writes one or more constructors to a builder.
+ *
+ * @param options The settings of the constructor. See `TsConstructor` for the available properties.
+ * @example
+ * ```ts
+ * tsConstructor({
+ *   parameters: [tsConstructorParameter('x', { type: 'number' }), 'y'],
+ *   body: 'this.x = x;',
+ * });
+ * // Emits:
+ * // constructor(x: number, y) {
+ * //   this.x = x;
+ * // }
+ * ```
+ */
 export const tsConstructor = Object.assign(createConstructor, {
     write: writeTsNodes,
 });

package/dist/src/ast/nodes/decorator.d.ts

@@ -8,9 +8,30 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     function: TsReference<TBuilder> | BasicAppendValue<TBuilder>;
     arguments?: Nullable<Nullable<TsArgument<TBuilder> | TsValue<TBuilder>>[]>;
 }>;
+/**
+ * Represents a decorator, such as `@decorator` or `@decorator(arg1, arg2)`.
+ *
+ * Written in this order: the `@` sign, the function, then the arguments in parentheses when they are set.
+ *
+ * @template TBuilder The type of the source builder the decorator is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsDecorator
+ */
 export declare class TsDecorator<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The function that is called as the decorator, such as `decorator` in `@decorator`. It is written right after the
+     * `@` sign, and nodes are written with their own output.
+     */
     function: TsReference<TBuilder> | BasicAppendValue<TBuilder>;
+    /**
+     * The arguments written in parentheses after the function, or `null` to write no parentheses. An empty array writes
+     * `()`, and more than two arguments are written one per line.
+     */
     arguments: (TsArgument<TBuilder> | TsValue<TBuilder>)[] | null;
+    /**
+     * Initializes a new instance of the TsDecorator class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
@@ -18,6 +39,20 @@ declare const createDecorator: <TBuilder extends SourceBuilder>(fn: Options<TBui
 declare const writeDecorators: <TBuilder extends SourceBuilder>(builder: TBuilder, nodes: SingleOrMultiple<Nullable<TsDecorator<TBuilder> | AppendValue<TBuilder>>>, options?: {
     multiline?: boolean;
 }) => void;
+/**
+ * Factory for creating decorator nodes. The `write` function writes one or more decorators to a builder. With
+ * `multiline` each decorator gets its own line, otherwise the decorators are separated by spaces.
+ *
+ * @param fn The decorator function, such as `Injectable`.
+ * @param args The arguments of the decorator. Omit them to write no parentheses.
+ * @param options The settings of the decorator. See `TsDecorator` for the available properties.
+ * @example
+ * ```ts
+ * tsDecorator('Injectable', ["'root'"]);
+ * // Emits:
+ * // @Injectable('root')
+ * ```
+ */
 export declare const tsDecorator: typeof createDecorator & {
     write: typeof writeDecorators;
 };

package/dist/src/ast/nodes/decorator.js

@@ -2,9 +2,30 @@ import { notNullish, toArray, } from '@goast/core';
 import { TsNode } from '../node.js';
 import { writeTsNode } from '../utils/write-ts-nodes.js';
 import { tsArgument } from './argument.js';
+/**
+ * Represents a decorator, such as `@decorator` or `@decorator(arg1, arg2)`.
+ *
+ * Written in this order: the `@` sign, the function, then the arguments in parentheses when they are set.
+ *
+ * @template TBuilder The type of the source builder the decorator is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsDecorator
+ */
 export class TsDecorator extends TsNode {
+    /**
+     * The function that is called as the decorator, such as `decorator` in `@decorator`. It is written right after the
+     * `@` sign, and nodes are written with their own output.
+     */
     function;
+    /**
+     * The arguments written in parentheses after the function, or `null` to write no parentheses. An empty array writes
+     * `()`, and more than two arguments are written one per line.
+     */
     arguments;
+    /**
+     * Initializes a new instance of the TsDecorator class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.function = options.function;
@@ -30,6 +51,20 @@ const writeDecorators = (builder, nodes, options) => {
         b.append(options?.multiline ? '\n' : ' ');
     });
 };
+/**
+ * Factory for creating decorator nodes. The `write` function writes one or more decorators to a builder. With
+ * `multiline` each decorator gets its own line, otherwise the decorators are separated by spaces.
+ *
+ * @param fn The decorator function, such as `Injectable`.
+ * @param args The arguments of the decorator. Omit them to write no parentheses.
+ * @param options The settings of the decorator. See `TsDecorator` for the available properties.
+ * @example
+ * ```ts
+ * tsDecorator('Injectable', ["'root'"]);
+ * // Emits:
+ * // @Injectable('root')
+ * ```
+ */
 export const tsDecorator = Object.assign(createDecorator, {
     write: writeDecorators,
 });

package/dist/src/ast/nodes/doc-tag.d.ts

@@ -8,10 +8,34 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     type?: Nullable<TsType<TBuilder>>;
     text?: Nullable<BasicAppendValue<TBuilder>>;
 }>;
+/**
+ * Represents a single tag of a doc comment, such as `@param x The x value.` or `@returns`.
+ *
+ * Written in this order: the `@` sign and the tag name, the type in curly braces when set, then the text. The parts are
+ * separated by spaces. The enclosing doc comment writes its tags one per line.
+ *
+ * @template TBuilder The type of the source builder the doc tag is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsDocTag
+ */
 export declare class TsDocTag<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The name of the tag, written after the `@` sign, such as `param`. Any name is written, so custom tags work too.
+     */
     tag: string;
+    /**
+     * The type written in curly braces after the tag name, such as `{number}`. Nothing is written when `null`.
+     */
     type: TsType<TBuilder> | null;
+    /**
+     * The text written after the tag name and the type, such as the description of a parameter. Nothing is written when
+     * `null`.
+     */
     text: BasicAppendValue<TBuilder> | null;
+    /**
+     * Initializes a new instance of the TsDocTag class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
@@ -67,6 +91,21 @@ type _TsDocTagArgsMap<TBuilder extends SourceBuilder> = {
 };
 type _TsDocTagArgs<TTagName extends StringSuggestions<keyof _TsDocTagArgsMap<TBuilder>>, TBuilder extends SourceBuilder> = TTagName extends keyof _TsDocTagArgsMap<TBuilder> ? _TsDocTagArgsMap<TBuilder>[TTagName] extends (...args: any[]) => any ? ParametersWithOverloads<_TsDocTagArgsMap<TBuilder>[TTagName]> : never : [options?: _TsDocTagOpt<TBuilder>];
 declare function createDocTag<TTagName extends StringSuggestions<keyof _TsDocTagArgsMap<TBuilder>>, TBuilder extends SourceBuilder>(tag: TTagName, ...args: _TsDocTagArgs<TTagName, TBuilder>): TsDocTag<TBuilder>;
+/**
+ * Factory for creating doc tag nodes. The arguments depend on the tag. For example, `param` takes a name and a
+ * description, and `author` takes a name and an optional email address, which it writes in angle brackets. Tags such as
+ * `returns` take a single description. Any tag accepts an optional last argument with the `type`, `text` or `inject`
+ * settings. The `write` function writes one or more tags to a builder.
+ *
+ * @param tag The name of the tag, written after the `@` sign.
+ * @param args The arguments of the tag. See the overloads of `tsDocTag` for the arguments that each tag takes.
+ * @example
+ * ```ts
+ * tsDocTag('param', 'x', 'The x coordinate.', { type: 'number' });
+ * // Emits:
+ * // @param {number} x The x coordinate.
+ * ```
+ */
 export declare const tsDocTag: typeof createDocTag & {
     write: typeof writeTsNodes;
 };

package/dist/src/ast/nodes/doc-tag.js

@@ -2,10 +2,34 @@ import { basicAppendValueGroup, notNullish, } from '@goast/core';
 import { isTypeScriptAppendValue } from '../../file-builder.js';
 import { TsNode } from '../node.js';
 import { writeTsNode, writeTsNodes } from '../utils/write-ts-nodes.js';
+/**
+ * Represents a single tag of a doc comment, such as `@param x The x value.` or `@returns`.
+ *
+ * Written in this order: the `@` sign and the tag name, the type in curly braces when set, then the text. The parts are
+ * separated by spaces. The enclosing doc comment writes its tags one per line.
+ *
+ * @template TBuilder The type of the source builder the doc tag is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsDocTag
+ */
 export class TsDocTag extends TsNode {
+    /**
+     * The name of the tag, written after the `@` sign, such as `param`. Any name is written, so custom tags work too.
+     */
     tag;
+    /**
+     * The type written in curly braces after the tag name, such as `{number}`. Nothing is written when `null`.
+     */
     type;
+    /**
+     * The text written after the tag name and the type, such as the description of a parameter. Nothing is written when
+     * `null`.
+     */
     text;
+    /**
+     * Initializes a new instance of the TsDocTag class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.tag = options.tag;
@@ -57,6 +81,21 @@ function createDocTag(tag, ...args) {
         inject: opt.inject,
     });
 }
+/**
+ * Factory for creating doc tag nodes. The arguments depend on the tag. For example, `param` takes a name and a
+ * description, and `author` takes a name and an optional email address, which it writes in angle brackets. Tags such as
+ * `returns` take a single description. Any tag accepts an optional last argument with the `type`, `text` or `inject`
+ * settings. The `write` function writes one or more tags to a builder.
+ *
+ * @param tag The name of the tag, written after the `@` sign.
+ * @param args The arguments of the tag. See the overloads of `tsDocTag` for the arguments that each tag takes.
+ * @example
+ * ```ts
+ * tsDocTag('param', 'x', 'The x coordinate.', { type: 'number' });
+ * // Emits:
+ * // @param {number} x The x coordinate.
+ * ```
+ */
 export const tsDocTag = Object.assign(createDocTag, {
     write: writeTsNodes,
 });

package/dist/src/ast/nodes/doc.d.ts

@@ -9,9 +9,32 @@ type Options<TBuilder extends SourceBuilder, TInjects extends string = never> =
     description?: Nullable<BasicAppendValue<TBuilder>>;
     tags?: Nullable<Nullable<TsDocTag<TBuilder>>[]>;
 }>;
+/**
+ * Represents a doc comment, which is written above the node that it documents. Nothing is written when the doc has
+ * neither a description nor tags.
+ *
+ * Written in this order: the description, an empty line when both a description and tags are set, then the tags, one
+ * per line. The comment starts on its own line and is followed by a line break.
+ *
+ * @template TBuilder The type of the source builder the doc comment is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsDoc
+ */
 export declare class TsDoc<TBuilder extends SourceBuilder, TInjects extends string = never> extends TsNode<TBuilder, TInjects | Injects> {
+    /**
+     * The text at the top of the doc comment. Each line of the text is prefixed with an asterisk. Nothing is written when
+     * `null`.
+     */
     description: BasicAppendValue<TBuilder> | null;
+    /**
+     * The tags written below the description, one per line, such as `@param` or `@returns`. An empty line separates them
+     * from the description.
+     */
     tags: TsDocTag<TBuilder>[];
+    /**
+     * Initializes a new instance of the TsDoc class.
+     * @param options The options to use for this instance.
+     */
     constructor(options: Options<TBuilder, TInjects>);
     protected onWrite(builder: TBuilder): void;
 }
@@ -21,6 +44,21 @@ declare function getDoc<TBuilder extends SourceBuilder>(baseDoc: TsDoc<TBuilder>
     generics?: Nullable<Nullable<TsGenericParameter<TBuilder> | BasicAppendValue<TBuilder>>[]>;
 }): TsDoc<TBuilder> | null;
 declare function isDocEmpty(doc: Nullable<TsDoc<SourceBuilder>>): boolean;
+/**
+ * Factory for creating doc comment nodes. The `write` function writes a doc comment to a builder. The `get` function
+ * returns a doc with `@template` tags for the described generics and `@param` tags for the described parameters, placed
+ * before the existing tags. The `isEmpty` function tells whether a doc has nothing to write.
+ *
+ * @param options The settings of the doc comment. See `TsDoc` for the available properties.
+ * @example
+ * ```ts
+ * tsDoc({ description: 'Creates a user.', tags: [tsDocTag('returns', 'The new user.')] });
+ * // Emits the lines of the doc comment. The opening and closing delimiters are left out here:
+ * // Creates a user.
+ * //
+ * // @returns The new user.
+ * ```
+ */
 export declare const tsDoc: typeof createDoc & {
     write: typeof writeTsNodes;
     get: typeof getDoc;

package/dist/src/ast/nodes/doc.js

@@ -4,9 +4,32 @@ import { writeTsNodes } from '../utils/write-ts-nodes.js';
 import { tsDocTag } from './doc-tag.js';
 import { TsGenericParameter } from './generic-parameter.js';
 import { TsParameter } from './parameter.js';
+/**
+ * Represents a doc comment, which is written above the node that it documents. Nothing is written when the doc has
+ * neither a description nor tags.
+ *
+ * Written in this order: the description, an empty line when both a description and tags are set, then the tags, one
+ * per line. The comment starts on its own line and is followed by a line break.
+ *
+ * @template TBuilder The type of the source builder the doc comment is written to.
+ * @template TInjects Additional names of custom injection points (`before*` and `after*`) accepted by this node.
+ * @see tsDoc
+ */
 export class TsDoc extends TsNode {
+    /**
+     * The text at the top of the doc comment. Each line of the text is prefixed with an asterisk. Nothing is written when
+     * `null`.
+     */
     description;
+    /**
+     * The tags written below the description, one per line, such as `@param` or `@returns`. An empty line separates them
+     * from the description.
+     */
     tags;
+    /**
+     * Initializes a new instance of the TsDoc class.
+     * @param options The options to use for this instance.
+     */
     constructor(options) {
         super(options);
         this.description = options.description ?? null;
@@ -50,6 +73,21 @@ function getDoc(baseDoc, options) {
 function isDocEmpty(doc) {
     return !doc || (!doc.description && doc.tags.length === 0);
 }
+/**
+ * Factory for creating doc comment nodes. The `write` function writes a doc comment to a builder. The `get` function
+ * returns a doc with `@template` tags for the described generics and `@param` tags for the described parameters, placed
+ * before the existing tags. The `isEmpty` function tells whether a doc has nothing to write.
+ *
+ * @param options The settings of the doc comment. See `TsDoc` for the available properties.
+ * @example
+ * ```ts
+ * tsDoc({ description: 'Creates a user.', tags: [tsDocTag('returns', 'The new user.')] });
+ * // Emits the lines of the doc comment. The opening and closing delimiters are left out here:
+ * // Creates a user.
+ * //
+ * // @returns The new user.
+ * ```
+ */
 export const tsDoc = Object.assign(createDoc, {
     write: writeTsNodes,
     get: getDoc,