/
TSDocTagDefinition.ts
91 lines (79 loc) · 2.5 KB
/
TSDocTagDefinition.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
import { StringChecks } from '../parser/StringChecks';
import { Standardization } from '../details/Standardization';
/**
* Determines the type of syntax for a TSDocTagDefinition
*/
export enum TSDocTagSyntaxKind {
/**
* The tag is intended to be an inline tag. For example: `{@link}`.
*/
InlineTag,
/**
* The tag is intended to be a block tag that starts a new documentation
* section. For example: `@remarks`
*/
BlockTag,
/**
* The tag is intended to be a modifier tag whose presence indicates
* an aspect of the associated API item. For example: `@internal`
*/
ModifierTag
}
/**
* Constructor parameters for {@link TSDocTagDefinition}
*/
export interface ITSDocTagDefinitionParameters {
tagName: string;
syntaxKind: TSDocTagSyntaxKind;
allowMultiple?: boolean;
}
/**
* @internal
*/
export interface ITSDocTagDefinitionInternalParameters extends ITSDocTagDefinitionParameters {
standardization: Standardization;
}
/**
* Defines a TSDoc tag that will be understood by the TSDocParser.
*/
export class TSDocTagDefinition {
/**
* The TSDoc tag name. TSDoc tag names start with an at-sign (`@`) followed
* by ASCII letters using "camelCase" capitalization.
*/
public readonly tagName: string;
/**
* The TSDoc tag name in all capitals, which is used for performing
* case-insensitive comparisons or lookups.
*/
public readonly tagNameWithUpperCase: string;
/**
* Specifies the expected syntax for this tag.
*/
public readonly syntaxKind: TSDocTagSyntaxKind;
/**
* Indicates the level of support expected from documentation tools that implement
* the standard.
*/
public readonly standardization: Standardization;
/**
* If true, then this TSDoc tag may appear multiple times in a doc comment.
* By default, a tag may only appear once.
*/
public readonly allowMultiple: boolean;
public constructor(parameters: ITSDocTagDefinitionParameters) {
StringChecks.validateTSDocTagName(parameters.tagName);
this.tagName = parameters.tagName;
this.tagNameWithUpperCase = parameters.tagName.toUpperCase();
this.syntaxKind = parameters.syntaxKind;
this.standardization =
(parameters as ITSDocTagDefinitionInternalParameters).standardization || Standardization.None;
this.allowMultiple = !!parameters.allowMultiple;
}
/**
* Throws an exception if `tagName` is not a valid TSDoc tag name.
*/
public static validateTSDocTagName(tagName: string): void {
StringChecks.validateTSDocTagName(tagName);
}
}