1 | import type { Reflection } from "../reflections";
|
2 | import { ReflectionSymbolId } from "../reflections/ReflectionSymbolId";
|
3 | import type { Serializer, Deserializer, JSONOutput } from "../../serialization";
|
4 | /**
|
5 | * Represents a parsed piece of a comment.
|
6 | * @category Comments
|
7 | * @see {@link JSONOutput.CommentDisplayPart}
|
8 | */
|
9 | export type CommentDisplayPart =
|
10 | /**
|
11 | * Represents a plain text portion of the comment, may contain markdown
|
12 | */
|
13 | {
|
14 | kind: "text";
|
15 | text: string;
|
16 | }
|
17 | /**
|
18 | * Represents a code block separated out form the plain text entry so
|
19 | * that TypeDoc knows to skip it when parsing relative links and inline tags.
|
20 | **/
|
21 | | {
|
22 | kind: "code";
|
23 | text: string;
|
24 | }
|
25 | /**
|
26 | * Represents an inline tag like `{@link Foo}`
|
27 | */
|
28 | | InlineTagDisplayPart
|
29 | /**
|
30 | * Represents a reference to a path relative to where the comment resides.
|
31 | * This is used to detect and copy relative image links.
|
32 | * Use {@link FileRegistry} to determine what path on disc this refers to.
|
33 | */
|
34 | | RelativeLinkDisplayPart;
|
35 | /**
|
36 | * The `@link`, `@linkcode`, and `@linkplain` tags may have a `target`
|
37 | * property set indicating which reflection/url they link to. They may also
|
38 | * have a `tsLinkText` property which includes the part of the `text` which
|
39 | * TypeScript thinks should be displayed as the link text.
|
40 | * @category Comments
|
41 | */
|
42 | export interface InlineTagDisplayPart {
|
43 | kind: "inline-tag";
|
44 | tag: `@${string}`;
|
45 | text: string;
|
46 | target?: Reflection | string | ReflectionSymbolId;
|
47 | tsLinkText?: string;
|
48 | }
|
49 | /**
|
50 | * This is used for relative links within comments/documents.
|
51 | * It is used to mark pieces of text which need to be replaced
|
52 | * to make links work properly.
|
53 | */
|
54 | export interface RelativeLinkDisplayPart {
|
55 | kind: "relative-link";
|
56 | /**
|
57 | * The original relative text from the parsed comment.
|
58 | */
|
59 | text: string;
|
60 | /**
|
61 | * A link to either some document outside of the project or a reflection.
|
62 | * This may be `undefined` if the relative path does not exist.
|
63 | */
|
64 | target: number | undefined;
|
65 | }
|
66 | /**
|
67 | * A model that represents a single TypeDoc comment tag.
|
68 | *
|
69 | * Tags are stored in the {@link Comment.blockTags} property.
|
70 | * @category Comments
|
71 | */
|
72 | export declare class CommentTag {
|
73 | /**
|
74 | * The name of this tag, e.g. `@returns`, `@example`
|
75 | */
|
76 | tag: `@${string}`;
|
77 | /**
|
78 | * Some tags, (`@typedef`, `@param`, `@property`, etc.) may have a user defined identifier associated with them.
|
79 | * If this tag is one of those, it will be parsed out and included here.
|
80 | */
|
81 | name?: string;
|
82 | /**
|
83 | * The actual body text of this tag.
|
84 | */
|
85 | content: CommentDisplayPart[];
|
86 | /**
|
87 | * A flag which may be set by plugins to prevent TypeDoc from rendering this tag, if the plugin provides
|
88 | * custom rendering. Note: This flag is **not** serialized, it is expected to be set just before the comment
|
89 | * is rendered.
|
90 | */
|
91 | skipRendering: boolean;
|
92 | /**
|
93 | * Create a new CommentTag instance.
|
94 | */
|
95 | constructor(tag: `string}`, text: CommentDisplayPart[]);
{ |
96 | /**
|
97 | * Checks if this block tag is roughly equal to the other tag.
|
98 | * This isn't exactly equal, but just "roughly equal" by the tag
|
99 | * text.
|
100 | */
|
101 | similarTo(other: CommentTag): boolean;
|
102 | clone(): CommentTag;
|
103 | toObject(serializer: Serializer): JSONOutput.CommentTag;
|
104 | fromObject(de: Deserializer, obj: JSONOutput.CommentTag): void;
|
105 | }
|
106 | /**
|
107 | * A model that represents a comment.
|
108 | *
|
109 | * Instances of this model are created by the CommentPlugin. You can retrieve comments
|
110 | * through the { DeclarationReflection.comment} property.
|
111 | * Comments
|
112 | */
|
113 | export declare class Comment {
|
114 | /**
|
115 | * Debugging utility for combining parts into a simple string. Not suitable for
|
116 | * rendering, but can be useful in tests.
|
117 | */
|
118 | static combineDisplayParts(parts: readonly CommentDisplayPart[] | undefined): string;
|
119 | /**
|
120 | * Helper utility to clone {@link Comment.summary} or {@link CommentTag.content}
|
121 | */
|
122 | static cloneDisplayParts(parts: readonly CommentDisplayPart[]): ({
|
123 | kind: "text";
|
124 | text: string;
|
125 | } | {
|
126 | kind: "code";
|
127 | text: string;
|
128 | } | {
|
129 | kind: "inline-tag";
|
130 | tag: `@${string}`;
|
131 | text: string;
|
132 | target?: Reflection | string | ReflectionSymbolId;
|
133 | tsLinkText?: string;
|
134 | } | {
|
135 | kind: "relative-link";
|
136 | /**
|
137 | * The original relative text from the parsed comment.
|
138 | */
|
139 | text: string;
|
140 | /**
|
141 | * A link to either some document outside of the project or a reflection.
|
142 | * This may be `undefined` if the relative path does not exist.
|
143 | */
|
144 | target: number | undefined;
|
145 | })[];
|
146 | static serializeDisplayParts(serializer: Serializer, parts: CommentDisplayPart[]): JSONOutput.CommentDisplayPart[];
|
147 | /** @hidden no point in showing this signature in api docs */
|
148 | static serializeDisplayParts(serializer: Serializer, parts: CommentDisplayPart[] | undefined): JSONOutput.CommentDisplayPart[] | undefined;
|
149 | static deserializeDisplayParts(de: Deserializer, parts: JSONOutput.CommentDisplayPart[]): CommentDisplayPart[];
|
150 | /**
|
151 | * Splits the provided parts into a header (first line, as a string)
|
152 | * and body (remaining lines). If the header line contains inline tags
|
153 | * they will be serialized to a string.
|
154 | */
|
155 | static splitPartsToHeaderAndBody(parts: readonly CommentDisplayPart[]): {
|
156 | header: string;
|
157 | body: CommentDisplayPart[];
|
158 | };
|
159 | /**
|
160 | * The content of the comment which is not associated with a block tag.
|
161 | */
|
162 | summary: CommentDisplayPart[];
|
163 | /**
|
164 | * All associated block level tags.
|
165 | */
|
166 | blockTags: CommentTag[];
|
167 | /**
|
168 | * All modifier tags present on the comment, e.g. `@alpha`, `@beta`.
|
169 | */
|
170 | modifierTags: Set<`@${string}`>;
|
171 | /**
|
172 | * Label associated with this reflection, if any (https://tsdoc.org/pages/tags/label/)
|
173 | */
|
174 | label?: string;
|
175 | /**
|
176 | * Full path to the file where this comment originated from, if any.
|
177 | * This field will not be serialized, so will not be present when handling JSON-revived reflections.
|
178 | *
|
179 | * Note: This field is non-enumerable to make testing comment contents with `deepEqual` easier.
|
180 | */
|
181 | sourcePath?: string;
|
182 | /**
|
183 | * Internal discovery ID used to prevent symbol comments from
|
184 | * being duplicated on signatures. Only set when the comment was created
|
185 | * from a `ts.CommentRange`.
|
186 | * @internal
|
187 | */
|
188 | discoveryId?: number;
|
189 | /**
|
190 | * If the comment was inherited from a different "parent" declaration
|
191 | * (see #2545), then it is desirable to know this as any `@param` tags
|
192 | * which do not apply should not cause warnings. This is not serialized,
|
193 | * and only set when the comment was created from a `ts.CommentRange`.
|
194 | */
|
195 | inheritedFromParentDeclaration?: boolean;
|
196 | /**
|
197 | * Creates a new Comment instance.
|
198 | */
|
199 | constructor(summary?: CommentDisplayPart[], blockTags?: CommentTag[], modifierTags?: Set<`string}`>);
{ |
200 | /**
|
201 | * Checks if this comment is roughly equal to the other comment.
|
202 | * This isn't exactly equal, but just "roughly equal" by the comment
|
203 | * text.
|
204 | */
|
205 | similarTo(other: Comment): boolean;
|
206 | /**
|
207 | * Create a deep clone of this comment.
|
208 | */
|
209 | clone(): Comment;
|
210 | /**
|
211 | * Returns true if this comment is completely empty.
|
212 | * @internal
|
213 | */
|
214 | isEmpty(): boolean;
|
215 | /**
|
216 | * Has this comment a visible component?
|
217 | *
|
218 | * @returns TRUE when this comment has a visible component.
|
219 | */
|
220 | hasVisibleComponent(): boolean;
|
221 | /**
|
222 | * Test whether this comment contains a tag with the given name.
|
223 | *
|
224 | * @param tagName The name of the tag to look for.
|
225 | * @returns TRUE when this comment contains a tag with the given name, otherwise FALSE.
|
226 | */
|
227 | hasModifier(tagName: `string}`): boolean;
{ |
228 | removeModifier(tagName: `string}`): void;
{ |
229 | /**
|
230 | * Return the first tag with the given name.
|
231 | *
|
232 | * @param tagName The name of the tag to look for.
|
233 | * @returns The found tag or undefined.
|
234 | */
|
235 | getTag(tagName: `string}`): CommentTag | undefined;
{ |
236 | /**
|
237 | * Get all tags with the given tag name.
|
238 | */
|
239 | getTags(tagName: `string}`): CommentTag[];
{ |
240 | getIdentifiedTag(identifier: string, tagName: ` {string}`): CommentTag | undefined;
|
241 | /**
|
242 | * Removes all block tags with the given tag name from the comment.
|
243 | * @param tagName
|
244 | */
|
245 | removeTags(tagName: `string}`): void;
{ |
246 | toObject(serializer: Serializer): JSONOutput.Comment;
|
247 | fromObject(de: Deserializer, obj: JSONOutput.Comment): void;
|
248 | }
|