1 | ;
|
2 | Object.defineProperty(exports, "__esModule", { value: true });
|
3 | exports.StandardTags = void 0;
|
4 | var TSDocTagDefinition_1 = require("../configuration/TSDocTagDefinition");
|
5 | var Standardization_1 = require("./Standardization");
|
6 | /**
|
7 | * Tags whose meaning is defined by the TSDoc standard.
|
8 | */
|
9 | var StandardTags = /** @class */ (function () {
|
10 | function StandardTags() {
|
11 | }
|
12 | StandardTags._defineTag = function (parameters) {
|
13 | return new TSDocTagDefinition_1.TSDocTagDefinition(parameters);
|
14 | };
|
15 | /**
|
16 | * (Discretionary)
|
17 | *
|
18 | * Suggested meaning: Designates that an API item's release stage is "alpha".
|
19 | * It is intended to be used by third-party developers eventually, but has not
|
20 | * yet been released. The tooling may trim the declaration from a public release.
|
21 | *
|
22 | * @remarks
|
23 | * Example implementations: API Extractor
|
24 | */
|
25 | StandardTags.alpha = StandardTags._defineTag({
|
26 | tagName: '@alpha',
|
27 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
28 | standardization: Standardization_1.Standardization.Discretionary
|
29 | });
|
30 | /**
|
31 | * (Discretionary)
|
32 | *
|
33 | * Suggested meaning: Designates that an API item's release stage is "beta".
|
34 | * It has been released to third-party developers experimentally for the purpose of
|
35 | * collecting feedback. The API should not be used in production, because its contract may
|
36 | * change without notice. The tooling may trim the declaration from a public release,
|
37 | * but may include it in a developer preview release.
|
38 | *
|
39 | * @remarks
|
40 | * Example implementations: API Extractor
|
41 | *
|
42 | * Synonyms: `@experimental`
|
43 | */
|
44 | StandardTags.beta = StandardTags._defineTag({
|
45 | tagName: '@beta',
|
46 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
47 | standardization: Standardization_1.Standardization.Discretionary
|
48 | });
|
49 | /**
|
50 | * (Extended)
|
51 | *
|
52 | * ECMAScript decorators are sometimes an important part of an API contract.
|
53 | * However, today the TypeScript compiler does not represent decorators in the
|
54 | * .d.ts output files used by API consumers. The `@decorator` tag provides a workaround,
|
55 | * enabling a decorator expressions to be quoted in a doc comment.
|
56 | *
|
57 | * @example
|
58 | * ```ts
|
59 | * class Book {
|
60 | * /**
|
61 | * * The title of the book.
|
62 | * * @decorator `@jsonSerialized`
|
63 | * * @decorator `@jsonFormat(JsonFormats.Url)`
|
64 | * *
|
65 | *+/
|
66 | * @jsonSerialized
|
67 | * @jsonFormat(JsonFormats.Url)
|
68 | * public website: string;
|
69 | * }
|
70 | * ```
|
71 | */
|
72 | StandardTags.decorator = StandardTags._defineTag({
|
73 | tagName: '@decorator',
|
74 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
75 | allowMultiple: true,
|
76 | standardization: Standardization_1.Standardization.Extended
|
77 | });
|
78 | /**
|
79 | * (Extended)
|
80 | *
|
81 | * This block tag is used to document the default value for a field or property,
|
82 | * if a value is not assigned explicitly.
|
83 | *
|
84 | * @remarks
|
85 | * This tag should only be used with fields or properties that are members of a class or interface.
|
86 | */
|
87 | StandardTags.defaultValue = StandardTags._defineTag({
|
88 | tagName: '@defaultValue',
|
89 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
90 | standardization: Standardization_1.Standardization.Extended
|
91 | });
|
92 | /**
|
93 | * (Core)
|
94 | *
|
95 | * This block tag communicates that an API item is no longer supported and may be removed
|
96 | * in a future release. The `@deprecated` tag is followed by a sentence describing
|
97 | * the recommended alternative. It recursively applies to members of the container.
|
98 | * For example, if a class is deprecated, then so are all of its members.
|
99 | */
|
100 | StandardTags.deprecated = StandardTags._defineTag({
|
101 | tagName: '@deprecated',
|
102 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
103 | standardization: Standardization_1.Standardization.Core
|
104 | });
|
105 | /**
|
106 | * (Extended)
|
107 | *
|
108 | * When applied to a class or interface property, this indicates that the property
|
109 | * returns an event object that event handlers can be attached to. The event-handling
|
110 | * API is implementation-defined, but typically the property return type would be a class
|
111 | * with members such as `addHandler()` and `removeHandler()`. A documentation tool can
|
112 | * display such properties under an "Events" heading instead of the usual "Properties" heading.
|
113 | */
|
114 | StandardTags.eventProperty = StandardTags._defineTag({
|
115 | tagName: '@eventProperty',
|
116 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
117 | standardization: Standardization_1.Standardization.Extended
|
118 | });
|
119 | /**
|
120 | * (Extended)
|
121 | *
|
122 | * Indicates a documentation section that should be presented as an example
|
123 | * illustrating how to use the API. It may include a code sample.
|
124 | */
|
125 | StandardTags.example = StandardTags._defineTag({
|
126 | tagName: '@example',
|
127 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
128 | allowMultiple: true,
|
129 | standardization: Standardization_1.Standardization.Extended
|
130 | });
|
131 | /**
|
132 | * (Discretionary)
|
133 | *
|
134 | * Suggested meaning: Same semantics as `@beta`, but used by tools that don't support
|
135 | * an `@alpha` release stage.
|
136 | *
|
137 | * @remarks
|
138 | * Example implementations: Angular API documenter
|
139 | *
|
140 | * Synonyms: `@beta`
|
141 | */
|
142 | StandardTags.experimental = StandardTags._defineTag({
|
143 | tagName: '@experimental',
|
144 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
145 | standardization: Standardization_1.Standardization.Discretionary
|
146 | });
|
147 | /**
|
148 | * (Extended)
|
149 | *
|
150 | * This inline tag is used to automatically generate an API item's documentation by
|
151 | * copying it from another API item. The inline tag parameter contains a reference
|
152 | * to the other item, which may be an unrelated class, or even an import from a
|
153 | * separate NPM package.
|
154 | *
|
155 | * @remarks
|
156 | * What gets copied
|
157 | *
|
158 | * The `@inheritDoc` tag does not copy the entire comment body. Only the following
|
159 | * components are copied:
|
160 | * - summary section
|
161 | * - `@remarks` block
|
162 | * - `@params` blocks
|
163 | * - `@typeParam` blocks
|
164 | * - `@returns` block
|
165 | * Other tags such as `@defaultValue` or `@example` are not copied, and need to be
|
166 | * explicitly included after the `@inheritDoc` tag.
|
167 | *
|
168 | * TODO: The notation for API item references is still being standardized. See this issue:
|
169 | * https://github.com/microsoft/tsdoc/issues/9
|
170 | */
|
171 | StandardTags.inheritDoc = StandardTags._defineTag({
|
172 | tagName: '@inheritDoc',
|
173 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.InlineTag,
|
174 | standardization: Standardization_1.Standardization.Extended
|
175 | });
|
176 | /**
|
177 | * (Discretionary)
|
178 | *
|
179 | * Suggested meaning: Designates that an API item is not planned to be used by
|
180 | * third-party developers. The tooling may trim the declaration from a public release.
|
181 | * In some implementations, certain designated packages may be allowed to consume
|
182 | * internal API items, e.g. because the packages are components of the same product.
|
183 | *
|
184 | * @remarks
|
185 | * Example implementations: API Extractor
|
186 | */
|
187 | StandardTags.internal = StandardTags._defineTag({
|
188 | tagName: '@internal',
|
189 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
190 | standardization: Standardization_1.Standardization.Discretionary
|
191 | });
|
192 | /**
|
193 | * (Core)
|
194 | *
|
195 | * The `{@label}` inline tag is used to label a declaration, so that it can be referenced
|
196 | * using a selector in the TSDoc declaration reference notation.
|
197 | *
|
198 | * @remarks
|
199 | * TODO: The `{@label}` notation is still being standardized. See this issue:
|
200 | * https://github.com/microsoft/tsdoc/issues/9
|
201 | */
|
202 | StandardTags.label = StandardTags._defineTag({
|
203 | tagName: '@label',
|
204 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.InlineTag,
|
205 | standardization: Standardization_1.Standardization.Core
|
206 | });
|
207 | /**
|
208 | * (Core)
|
209 | *
|
210 | * The `{@link}` inline tag is used to create hyperlinks to other pages in a
|
211 | * documentation system or general internet URLs. In particular, it supports
|
212 | * expressions for referencing API items.
|
213 | *
|
214 | * @remarks
|
215 | * TODO: The `{@link}` notation is still being standardized. See this issue:
|
216 | * https://github.com/microsoft/tsdoc/issues/9
|
217 | */
|
218 | StandardTags.link = StandardTags._defineTag({
|
219 | tagName: '@link',
|
220 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.InlineTag,
|
221 | allowMultiple: true,
|
222 | standardization: Standardization_1.Standardization.Core
|
223 | });
|
224 | /**
|
225 | * (Extended)
|
226 | *
|
227 | * This modifier has similar semantics to the `override` keyword in C# or Java.
|
228 | * For a member function or property, explicitly indicates that this definition
|
229 | * is overriding (i.e. redefining) the definition inherited from the base class.
|
230 | * The base class definition would normally be marked as `virtual`.
|
231 | *
|
232 | * @remarks
|
233 | * A documentation tool may enforce that the `@virtual`, `@override`, and/or `@sealed`
|
234 | * modifiers are consistently applied, but this is not required by the TSDoc standard.
|
235 | */
|
236 | StandardTags.override = StandardTags._defineTag({
|
237 | tagName: '@override',
|
238 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
239 | standardization: Standardization_1.Standardization.Extended
|
240 | });
|
241 | /**
|
242 | * (Core)
|
243 | *
|
244 | * Used to indicate a doc comment that describes an entire NPM package (as opposed
|
245 | * to an individual API item belonging to that package). The `@packageDocumentation` comment
|
246 | * is found in the *.d.ts file that acts as the entry point for the package, and it
|
247 | * should be the first `/**` comment encountered in that file. A comment containing a
|
248 | * `@packageDocumentation` tag should never be used to describe an individual API item.
|
249 | */
|
250 | StandardTags.packageDocumentation = StandardTags._defineTag({
|
251 | tagName: '@packageDocumentation',
|
252 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
253 | standardization: Standardization_1.Standardization.Core
|
254 | });
|
255 | /**
|
256 | * (Core)
|
257 | *
|
258 | * Used to document a function parameter. The `@param` tag is followed by a parameter
|
259 | * name, followed by a hyphen, followed by a description. The TSDoc parser recognizes
|
260 | * this syntax and will extract it into a DocParamBlock node.
|
261 | */
|
262 | StandardTags.param = StandardTags._defineTag({
|
263 | tagName: '@param',
|
264 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
265 | allowMultiple: true,
|
266 | standardization: Standardization_1.Standardization.Core
|
267 | });
|
268 | /**
|
269 | * (Core)
|
270 | *
|
271 | * Starts a section of additional documentation content that is not intended for a
|
272 | * public audience. A tool must omit this entire section from the API reference web site,
|
273 | * generated *.d.ts file, and any other outputs incorporating the content.
|
274 | */
|
275 | StandardTags.privateRemarks = StandardTags._defineTag({
|
276 | tagName: '@privateRemarks',
|
277 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
278 | standardization: Standardization_1.Standardization.Core
|
279 | });
|
280 | /**
|
281 | * (Discretionary)
|
282 | *
|
283 | * Suggested meaning: Designates that an API item's release stage is "public".
|
284 | * It has been officially released to third-party developers, and its signature is
|
285 | * guaranteed to be stable (e.g. following Semantic Versioning rules).
|
286 | *
|
287 | * @remarks
|
288 | * Example implementations: API Extractor
|
289 | */
|
290 | StandardTags.public = StandardTags._defineTag({
|
291 | tagName: '@public',
|
292 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
293 | standardization: Standardization_1.Standardization.Discretionary
|
294 | });
|
295 | /**
|
296 | * (Extended)
|
297 | *
|
298 | * This modifier tag indicates that an API item should be documented as being read-only,
|
299 | * even if the TypeScript type system may indicate otherwise. For example, suppose a
|
300 | * class property has a setter function that always throws an exception explaining that
|
301 | * the property cannot be assigned; in this situation, the `@readonly` modifier can be
|
302 | * added so that the property is shown as read-only in the documentation.
|
303 | *
|
304 | * @remarks
|
305 | * Example implementations: API Extractor
|
306 | */
|
307 | StandardTags.readonly = StandardTags._defineTag({
|
308 | tagName: '@readonly',
|
309 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
310 | standardization: Standardization_1.Standardization.Extended
|
311 | });
|
312 | /**
|
313 | * (Core)
|
314 | *
|
315 | * The main documentation for an API item is separated into a brief "summary" section,
|
316 | * optionally followed by a more detailed "remarks" section. On a documentation web site,
|
317 | * index pages (e.g. showing members of a class) will show only the brief summaries,
|
318 | * whereas a detail pages (e.g. describing a single member) will show the summary followed
|
319 | * by the remarks. The `@remarks` block tag ends the summary section, and begins the
|
320 | * remarks section for a doc comment.
|
321 | */
|
322 | StandardTags.remarks = StandardTags._defineTag({
|
323 | tagName: '@remarks',
|
324 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
325 | standardization: Standardization_1.Standardization.Core
|
326 | });
|
327 | /**
|
328 | * (Core)
|
329 | *
|
330 | * Used to document the return value for a function.
|
331 | */
|
332 | StandardTags.returns = StandardTags._defineTag({
|
333 | tagName: '@returns',
|
334 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
335 | standardization: Standardization_1.Standardization.Core
|
336 | });
|
337 | /**
|
338 | * (Extended)
|
339 | *
|
340 | * This modifier has similar semantics to the `sealed` keyword in C# or Java.
|
341 | * For a class, indicates that subclasses must not inherit from the class.
|
342 | * For a member function or property, indicates that subclasses must not override
|
343 | * (i.e. redefine) the member.
|
344 | *
|
345 | * @remarks
|
346 | * A documentation tool may enforce that the `@virtual`, `@override`, and/or `@sealed`
|
347 | * modifiers are consistently applied, but this is not required by the TSDoc standard.
|
348 | */
|
349 | StandardTags.sealed = StandardTags._defineTag({
|
350 | tagName: '@sealed',
|
351 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
352 | standardization: Standardization_1.Standardization.Extended
|
353 | });
|
354 | /**
|
355 | * (Extended)
|
356 | *
|
357 | * Used to build a list of references to an API item or other resource that may be related to the
|
358 | * current item.
|
359 | *
|
360 | * @remarks
|
361 | *
|
362 | * For example:
|
363 | *
|
364 | * ```ts
|
365 | * /**
|
366 | * * Parses a string containing a Uniform Resource Locator (URL).
|
367 | * * @see {@link ParsedUrl} for the returned data structure
|
368 | * * @see {@link https://tools.ietf.org/html/rfc1738|RFC 1738}
|
369 | * * for syntax
|
370 | * * @see your developer SDK for code samples
|
371 | * * @param url - the string to be parsed
|
372 | * * @returns the parsed result
|
373 | * */
|
374 | * function parseURL(url: string): ParsedUrl;
|
375 | * ```
|
376 | *
|
377 | * `@see` is a block tag. Each block becomes an item in the list of references. For example, a documentation
|
378 | * system might render the above blocks as follows:
|
379 | *
|
380 | * ```markdown
|
381 | * `function parseURL(url: string): ParsedUrl;`
|
382 | *
|
383 | * Parses a string containing a Uniform Resource Locator (URL).
|
384 | *
|
385 | * ## See Also
|
386 | * - ParsedUrl for the returned data structure
|
387 | * - RFC 1738 for syntax
|
388 | * - your developer SDK for code samples
|
389 | * ```
|
390 | *
|
391 | * NOTE: JSDoc attempts to automatically hyperlink the text immediately after `@see`. Because this is ambiguous
|
392 | * with plain text, TSDoc instead requires an explicit `{@link}` tag to make hyperlinks.
|
393 | */
|
394 | StandardTags.see = StandardTags._defineTag({
|
395 | tagName: '@see',
|
396 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
397 | standardization: Standardization_1.Standardization.Extended
|
398 | });
|
399 | /**
|
400 | * (Extended)
|
401 | *
|
402 | * Used to document an exception type that may be thrown by a function or property.
|
403 | *
|
404 | * @remarks
|
405 | *
|
406 | * A separate `@throws` block should be used to document each exception type. This tag is for informational
|
407 | * purposes only, and does not restrict other types from being thrown. It is suggested, but not required,
|
408 | * for the `@throws` block to start with a line containing only the name of the exception.
|
409 | *
|
410 | * For example:
|
411 | *
|
412 | * ```ts
|
413 | * /**
|
414 | * * Retrieves metadata about a book from the catalog.
|
415 | * *
|
416 | * * @param isbnCode - the ISBN number for the book
|
417 | * * @returns the retrieved book object
|
418 | * *
|
419 | * * @throws {@link IsbnSyntaxError}
|
420 | * * This exception is thrown if the input is not a valid ISBN number.
|
421 | * *
|
422 | * * @throws {@link book-lib#BookNotFoundError}
|
423 | * * Thrown if the ISBN number is valid, but no such book exists in the catalog.
|
424 | * *
|
425 | * * @public
|
426 | * */
|
427 | * function fetchBookByIsbn(isbnCode: string): Book;
|
428 | * ```
|
429 | */
|
430 | StandardTags.throws = StandardTags._defineTag({
|
431 | tagName: '@throws',
|
432 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
433 | allowMultiple: true,
|
434 | standardization: Standardization_1.Standardization.Extended
|
435 | });
|
436 | /**
|
437 | * (Core)
|
438 | *
|
439 | * Used to document a generic parameter. The `@typeParam` tag is followed by a parameter
|
440 | * name, followed by a hyphen, followed by a description. The TSDoc parser recognizes
|
441 | * this syntax and will extract it into a DocParamBlock node.
|
442 | */
|
443 | StandardTags.typeParam = StandardTags._defineTag({
|
444 | tagName: '@typeParam',
|
445 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.BlockTag,
|
446 | allowMultiple: true,
|
447 | standardization: Standardization_1.Standardization.Core
|
448 | });
|
449 | /**
|
450 | * (Extended)
|
451 | *
|
452 | * This modifier has similar semantics to the `virtual` keyword in C# or Java.
|
453 | * For a member function or property, explicitly indicates that subclasses may override
|
454 | * (i.e. redefine) the member.
|
455 | *
|
456 | * @remarks
|
457 | * A documentation tool may enforce that the `@virtual`, `@override`, and/or `@sealed`
|
458 | * modifiers are consistently applied, but this is not required by the TSDoc standard.
|
459 | */
|
460 | StandardTags.virtual = StandardTags._defineTag({
|
461 | tagName: '@virtual',
|
462 | syntaxKind: TSDocTagDefinition_1.TSDocTagSyntaxKind.ModifierTag,
|
463 | standardization: Standardization_1.Standardization.Extended
|
464 | });
|
465 | /**
|
466 | * Returns the full list of all core tags.
|
467 | */
|
468 | StandardTags.allDefinitions = [
|
469 | StandardTags.alpha,
|
470 | StandardTags.beta,
|
471 | StandardTags.defaultValue,
|
472 | StandardTags.decorator,
|
473 | StandardTags.deprecated,
|
474 | StandardTags.eventProperty,
|
475 | StandardTags.example,
|
476 | StandardTags.experimental,
|
477 | StandardTags.inheritDoc,
|
478 | StandardTags.internal,
|
479 | StandardTags.label,
|
480 | StandardTags.link,
|
481 | StandardTags.override,
|
482 | StandardTags.packageDocumentation,
|
483 | StandardTags.param,
|
484 | StandardTags.privateRemarks,
|
485 | StandardTags.public,
|
486 | StandardTags.readonly,
|
487 | StandardTags.remarks,
|
488 | StandardTags.returns,
|
489 | StandardTags.sealed,
|
490 | StandardTags.see,
|
491 | StandardTags.throws,
|
492 | StandardTags.typeParam,
|
493 | StandardTags.virtual
|
494 | ];
|
495 | return StandardTags;
|
496 | }());
|
497 | exports.StandardTags = StandardTags;
|
498 | //# sourceMappingURL=StandardTags.js.map |
\ | No newline at end of file |