Initial commit

node_modules/@microsoft/tsdoc/lib/nodes/DocComment.d.ts

@@ -0,0 +1,120 @@
+import { DocNode, DocNodeKind, type IDocNodeParameters } from './DocNode';
+import { DocSection } from './DocSection';
+import { StandardModifierTagSet } from '../details/StandardModifierTagSet';
+import type { DocBlock } from './DocBlock';
+import type { DocInheritDocTag } from './DocInheritDocTag';
+import { DocParamCollection } from './DocParamCollection';
+/**
+ * Constructor parameters for {@link DocComment}.
+ */
+export interface IDocCommentParameters extends IDocNodeParameters {
+}
+/**
+ * Represents an entire documentation comment conforming to the TSDoc structure.
+ * This is the root of the DocNode tree.
+ */
+export declare class DocComment extends DocNode {
+    /**
+     * The main documentation for an API item is separated into a brief "summary" section,
+     * optionally followed by an `@remarks` block containing additional details.
+     *
+     * @remarks
+     * The summary section should be brief. On a documentation web site, it will be shown
+     * on a page that lists summaries for many different API items.  On a detail page for
+     * a single item, the summary will be shown followed by the remarks section (if any).
+     */
+    summarySection: DocSection;
+    /**
+     * The main documentation for an API item is separated into a brief "summary" section
+     * optionally followed by an `@remarks` block containing additional details.
+     *
+     * @remarks
+     * Unlike the summary, the remarks block may contain lengthy documentation content.
+     * The remarks should not restate information from the summary, since the summary section
+     * will always be displayed wherever the remarks section appears.  Other sections
+     * (e.g. an `@example` block) will be shown after the remarks section.
+     */
+    remarksBlock: DocBlock | undefined;
+    /**
+     * The `@privateRemarks` tag starts a block of additional commentary that is not meant
+     * for an external audience.  A documentation tool must omit this content from an
+     * API reference web site.  It should also be omitted when generating a normalized
+     * *.d.ts file intended for third-party developers.
+     *
+     * @remarks
+     * A similar effect could be accomplished by enclosing content inside CommonMark
+     * `<!-- -->` comments, or by moving the content into a separate `//` TypeScript comment.
+     * However, the `@privateRemarks` tag is a more formal convention.
+     */
+    privateRemarks: DocBlock | undefined;
+    /**
+     * If present, this block indicates that an API item is no loner supported and may be
+     * removed in a future release.  The `@deprecated` tag must be followed by a sentence
+     * describing the recommended alternative.  Deprecation recursively applies to members
+     * of a container.  For example, if a class is deprecated, then so are all of its members.
+     */
+    deprecatedBlock: DocBlock | undefined;
+    /**
+     * The collection of parsed `@param` blocks for this doc comment.
+     */
+    readonly params: DocParamCollection;
+    /**
+     * The collection of parsed `@typeParam` blocks for this doc comment.
+     */
+    readonly typeParams: DocParamCollection;
+    /**
+     * The `@returns` block for this doc comment, or undefined if there is not one.
+     */
+    returnsBlock: DocBlock | undefined;
+    /**
+     * If this doc comment contains an `@inheritDoc` tag, it will be extracted and associated
+     * with the DocComment.
+     */
+    inheritDocTag: DocInheritDocTag | undefined;
+    /**
+     * The modifier tags for this DocComment.
+     */
+    readonly modifierTagSet: StandardModifierTagSet;
+    private _seeBlocks;
+    private _customBlocks;
+    /**
+     * Don't call this directly.  Instead use {@link TSDocParser}
+     * @internal
+     */
+    constructor(parameters: IDocCommentParameters);
+    /** @override */
+    get kind(): DocNodeKind | string;
+    /**
+     * The collection of all `@see` DockBlockTag nodes belonging to this doc comment.
+     */
+    get seeBlocks(): ReadonlyArray<DocBlock>;
+    /**
+     * The collection of all DocBlock nodes belonging to this doc comment.
+     */
+    get customBlocks(): ReadonlyArray<DocBlock>;
+    /**
+     * Append an item to the seeBlocks collection.
+     * @internal
+     */
+    _appendSeeBlock(block: DocBlock): void;
+    /**
+     * Append an item to the customBlocks collection.
+     */
+    appendCustomBlock(block: DocBlock): void;
+    /** @override */
+    protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
+    /**
+     * Generates a doc comment corresponding to the `DocComment` tree.  The output is in a normalized form,
+     * and may ignore formatting/spacing from the original input.
+     *
+     * @remarks
+     * After parsing a string, and possibly modifying the result, `emitAsTsdoc()` can be used to render the result
+     * as a doc comment in a normalized format.  It can also be used to emit a `DocComment` tree that was constructed
+     * manually.
+     *
+     * This method is provided as convenience for simple use cases.  To customize the output, or if you need
+     * to render into a `StringBuilder`, use the {@link TSDocEmitter} class instead.
+     */
+    emitAsTsdoc(): string;
+}
+//# sourceMappingURL=DocComment.d.ts.map