Class Comment

A model that represents a comment.

Instances of this model are created by the CommentPlugin. You can retrieve comments through the DeclarationReflection.comment property.

Constructors

constructor

new Comment(
    summary?: Models.CommentDisplayPart[],
    blockTags?: Models.CommentTag[],
    modifierTags?: Set<`@${string}`>,
): Models.Comment
Creates a new Comment instance.
Parameters
- summary: Models.CommentDisplayPart[] = []
- blockTags: Models.CommentTag[] = []
- modifierTags: Set<`@${string}`> = ...
Returns Models.Comment
- Defined in lib/models/Comment.ts:447

Methods

clone

clone(): Models.Comment
Create a deep clone of this comment.

Returns Models.Comment
- Defined in lib/models/Comment.ts:535

fromObject

fromObject(de: Deserializer, obj: JSONOutput.Comment): void
Parameters
- de: Deserializer
- obj: JSONOutput.Comment
Returns void
- Defined in lib/models/Comment.ts:628

getIdentifiedTag

getIdentifiedTag(
identifier: string,
tagName: `@${string}`,
): Models.CommentTag | undefined
Parameters
- identifier: string
- tagName: `@${string}`
Returns Models.CommentTag | undefined
- Defined in lib/models/Comment.ts:603

getShortSummary

getShortSummary(
useFirstParagraph: boolean,
): readonly Models.CommentDisplayPart[]
Gets either the @summary tag, or a short version of the comment summary section for rendering in module/namespace pages.
Parameters
- useFirstParagraph: boolean
Returns readonly Models.CommentDisplayPart[]
- Defined in lib/models/Comment.ts:462

getTag

getTag(tagName: `@${string}`): Models.CommentTag | undefined
Return the first tag with the given name.
Parameters
- tagName: `@${string}`
  The name of the tag to look for.
Returns Models.CommentTag | undefined
The found tag or undefined.
- Defined in lib/models/Comment.ts:592

getTags

getTags(tagName: `@${string}`): Models.CommentTag[]
Get all tags with the given tag name.
Parameters
- tagName: `@${string}`
Returns Models.CommentTag[]
- Defined in lib/models/Comment.ts:599

hasModifier

hasModifier(tagName: `@${string}`): boolean
Test whether this comment contains a tag with the given name.
Parameters
- tagName: `@${string}`
  The name of the tag to look for.
Returns boolean
TRUE when this comment contains a tag with the given name, otherwise FALSE.
- Defined in lib/models/Comment.ts:578

hasVisibleComponent

hasVisibleComponent(notRenderedTags?: readonly `@${string}`[]): boolean
Checks if this comment contains any visible text.
Parameters
- OptionalnotRenderedTags: readonly `@${string}`[]
Returns boolean
TRUE when this reflection has a visible comment.
- Defined in lib/models/Comment.ts:560

isEmpty

isEmpty(): boolean
Internal
Returns true if this comment is completely empty.

Returns boolean
- Defined in lib/models/Comment.ts:551

removeModifier

removeModifier(tagName: `@${string}`): void
Parameters
- tagName: `@${string}`
Returns void
- Defined in lib/models/Comment.ts:582

removeTags

removeTags(tagName: `@${string}`): void
Removes all block tags with the given tag name from the comment.
Parameters
- tagName: `@${string}`
Returns void
- Defined in lib/models/Comment.ts:613

similarTo

similarTo(other: Models.Comment): boolean
Checks if this comment is roughly equal to the other comment. This isn't exactly equal, but just "roughly equal" by the comment text.
Parameters
- other: Models.Comment
Returns boolean
- Defined in lib/models/Comment.ts:508

toObject

toObject(serializer: Serializer): JSONOutput.Comment
Parameters
- serializer: Serializer
Returns JSONOutput.Comment
- Defined in lib/models/Comment.ts:617

`Static`cloneDisplayParts

cloneDisplayParts(
parts: readonly Models.CommentDisplayPart[],
): Models.CommentDisplayPart[]
Helper utility to clone Comment.summary or CommentTag.content
Parameters
- parts: readonly Models.CommentDisplayPart[]
Returns Models.CommentDisplayPart[]
- Defined in lib/models/Comment.ts:200

`Static`combineDisplayParts

combineDisplayParts(
parts: readonly Models.CommentDisplayPart[] | undefined,
): string
Debugging utility for combining parts into a simple string. Not suitable for rendering, but can be useful in tests.
Parameters
- parts: readonly Models.CommentDisplayPart[] | undefined
Returns string
- Defined in lib/models/Comment.ts:174

`Static`deserializeDisplayParts

deserializeDisplayParts(
de: Deserializer,
parts: JSONOutput.CommentDisplayPart[],
): Models.CommentDisplayPart[]
Parameters
- de: Deserializer
- parts: JSONOutput.CommentDisplayPart[]
Returns Models.CommentDisplayPart[]
- Defined in lib/models/Comment.ts:248

`Static`serializeDisplayParts

serializeDisplayParts(
parts: Models.CommentDisplayPart[],
): JSONOutput.CommentDisplayPart[]
Parameters
- parts: Models.CommentDisplayPart[]
Returns JSONOutput.CommentDisplayPart[]
- Defined in lib/models/Comment.ts:207

`Static`splitPartsToHeaderAndBody

splitPartsToHeaderAndBody(
parts: readonly Models.CommentDisplayPart[],
): { body: Models.CommentDisplayPart[]; header: string }
Splits the provided parts into a header (first line, as a string) and body (remaining lines). If the header line contains inline tags they will be serialized to a string.
Parameters
- parts: readonly Models.CommentDisplayPart[]
Returns { body: Models.CommentDisplayPart[]; header: string }
- Defined in lib/models/Comment.ts:346

Properties

blockTags

blockTags: Models.CommentTag[] = []

All associated block level tags.

modifierTags

modifierTags: Set<`@${string}`> = ...

All modifier tags present on the comment, e.g. @alpha, @beta.

summary

summary: Models.CommentDisplayPart[]

The content of the comment which is not associated with a block tag.

`Optional` `Internal`discoveryId

discoveryId?: number

Internal discovery ID used to prevent symbol comments from being duplicated on signatures. Only set when the comment was created from a ts.CommentRange.

`Optional`inheritedFromParentDeclaration

inheritedFromParentDeclaration?: boolean

If the comment was inherited from a different "parent" declaration (see #2545), then it is desirable to know this as any @param tags which do not apply should not cause warnings. This is not serialized, and only set when the comment was created from a ts.CommentRange.

`Optional`label

label?: string

Label associated with this reflection, if any (https://tsdoc.org/pages/tags/label/)

`Optional`sourcePath

sourcePath?: NormalizedPath

Full path to the file where this comment originated from, if any. This field will not be serialized, so will not be present when handling JSON-revived reflections.

Note: This field is non-enumerable to make testing comment contents with deepEqual easier.

Class Comment

Index

Constructors

Methods

Properties

Constructors

constructor

Parameters

Returns Models.Comment

Methods

clone

Returns Models.Comment

fromObject

Parameters

Returns void

getIdentifiedTag

Parameters

Returns Models.CommentTag | undefined

getShortSummary

Parameters

Returns readonly Models.CommentDisplayPart[]

getTag

Parameters

Returns Models.CommentTag | undefined

getTags

Parameters

Returns Models.CommentTag[]

hasModifier

Parameters

Returns boolean

hasVisibleComponent

Parameters

Returns boolean

isEmpty

Returns boolean

removeModifier

Parameters

Returns void

removeTags

Parameters

Returns void

similarTo

Parameters

Returns boolean

toObject

Parameters

Returns JSONOutput.Comment

StaticcloneDisplayParts

Parameters

Returns Models.CommentDisplayPart[]

StaticcombineDisplayParts

Parameters

Returns string

StaticdeserializeDisplayParts

Parameters

Returns Models.CommentDisplayPart[]

StaticserializeDisplayParts

Parameters

Returns JSONOutput.CommentDisplayPart[]

StaticsplitPartsToHeaderAndBody

Parameters

Returns { body: Models.CommentDisplayPart[]; header: string }

Properties

blockTags

modifierTags

summary

Optional InternaldiscoveryId

OptionalinheritedFromParentDeclaration

Optionallabel

OptionalsourcePath

Settings

On This Page

`Static`cloneDisplayParts

`Static`combineDisplayParts

`Static`deserializeDisplayParts

`Static`serializeDisplayParts

`Static`splitPartsToHeaderAndBody

`Optional` `Internal`discoveryId

`Optional`inheritedFromParentDeclaration

`Optional`label

`Optional`sourcePath