UNPKG

8.22 kBTypeScriptView Raw
1import { Comment } from "../comments/comment.js";
2import type { ProjectReflection } from "./project.js";
3import type { NeverIfInternal } from "../../utils/index.js";
4import { ReflectionKind } from "./kind.js";
5import type { Serializer, Deserializer, JSONOutput } from "../../serialization/index.js";
6import type { ReflectionVariant } from "./variant.js";
7import type { DeclarationReflection } from "./declaration.js";
8import type { DocumentReflection } from "./document.js";
9import type { Internationalization, TranslatedString } from "../../internationalization/index.js";
10import type { ParameterReflection } from "./parameter.js";
11import type { ReferenceReflection } from "./reference.js";
12/**
13 * Reset the reflection id.
14 *
15 * Used by the test cases to ensure the reflection ids won't change between runs.
16 */
17export declare function resetReflectionID(): void;
18export declare enum ReflectionFlag {
19 None = 0,
20 Private = 1,
21 Protected = 2,
22 Public = 4,
23 Static = 8,
24 External = 16,
25 Optional = 32,
26 Rest = 64,
27 Abstract = 128,
28 Const = 256,
29 Readonly = 512,
30 Inherited = 1024
31}
32/**
33 * This must extend Array in order to work with Handlebar's each helper.
34 */
35export declare class ReflectionFlags {
36 private flags;
37 hasFlag(flag: ReflectionFlag): boolean;
38 /**
39 * Is this a private member?
40 */
41 get isPrivate(): boolean;
42 /**
43 * Is this a protected member?
44 */
45 get isProtected(): boolean;
46 /**
47 * Is this a public member?
48 */
49 get isPublic(): boolean;
50 /**
51 * Is this a static member?
52 */
53 get isStatic(): boolean;
54 /**
55 * Is this a declaration from an external document?
56 */
57 get isExternal(): boolean;
58 /**
59 * Whether this reflection is an optional component or not.
60 *
61 * Applies to function parameters and object members.
62 */
63 get isOptional(): boolean;
64 /**
65 * Whether it's a rest parameter, like `foo(...params);`.
66 */
67 get isRest(): boolean;
68 get isAbstract(): boolean;
69 get isConst(): boolean;
70 get isReadonly(): boolean;
71 get isInherited(): boolean;
72 setFlag(flag: ReflectionFlag, set: boolean): void;
73 getFlagStrings(i18n: Internationalization): TranslatedString[];
74 private setSingleFlag;
75 private static serializedFlags;
76 toObject(): JSONOutput.ReflectionFlags;
77 fromObject(obj: JSONOutput.ReflectionFlags): void;
78}
79export declare enum TraverseProperty {
80 Children = 0,
81 Documents = 1,
82 Parameters = 2,
83 TypeLiteral = 3,
84 TypeParameter = 4,
85 Signatures = 5,
86 IndexSignature = 6,
87 GetSignature = 7,
88 SetSignature = 8
89}
90export interface TraverseCallback {
91 /**
92 * May return false to bail out of any further iteration. To preserve backwards compatibility, if
93 * a function returns undefined, iteration must continue.
94 */
95 (reflection: Reflection, property: TraverseProperty): boolean | NeverIfInternal<void>;
96}
97export type ReflectionVisitor = {
98 [K in keyof ReflectionVariant]?: (refl: ReflectionVariant[K]) => void;
99};
100export type ReflectionId = number & {
101 __reflectionIdBrand: never;
102};
103/**
104 * Base class for all reflection classes.
105 *
106 * While generating a documentation, TypeDoc generates an instance of {@link ProjectReflection}
107 * as the root for all reflections within the project. All other reflections are represented
108 * by the {@link DeclarationReflection} class.
109 *
110 * This base class exposes the basic properties one may use to traverse the reflection tree.
111 * You can use the {@link ContainerReflection.children} and {@link parent} properties to walk the tree. The {@link ContainerReflection.groups} property
112 * contains a list of all children grouped and sorted for rendering.
113 * @category Reflections
114 */
115export declare abstract class Reflection {
116 /**
117 * Discriminator representing the type of reflection represented by this object.
118 */
119 abstract readonly variant: keyof ReflectionVariant;
120 /**
121 * Unique id of this reflection.
122 */
123 id: ReflectionId;
124 /**
125 * The symbol name of this reflection.
126 */
127 name: string;
128 /**
129 * The kind of this reflection.
130 */
131 kind: ReflectionKind;
132 flags: ReflectionFlags;
133 /**
134 * The reflection this reflection is a child of.
135 */
136 parent?: Reflection;
137 project: ProjectReflection;
138 /**
139 * The parsed documentation comment attached to this reflection.
140 */
141 comment?: Comment;
142 /**
143 * The url of this reflection in the generated documentation.
144 * TODO: Reflections shouldn't know urls exist. Move this to a serializer.
145 */
146 url?: string;
147 /**
148 * The name of the anchor of this child.
149 * TODO: Reflections shouldn't know anchors exist. Move this to a serializer.
150 */
151 anchor?: string;
152 /**
153 * Is the url pointing to an individual document?
154 *
155 * When FALSE, the url points to an anchor tag on a page of a different reflection.
156 * TODO: Reflections shouldn't know how they are rendered. Move this to the correct serializer.
157 */
158 hasOwnDocument?: boolean;
159 constructor(name: string, kind: ReflectionKind, parent?: Reflection);
160 /**
161 * Test whether this reflection is of the given kind.
162 */
163 kindOf(kind: ReflectionKind | ReflectionKind[]): boolean;
164 /**
165 * Return the full name of this reflection. Intended for use in debugging. For log messages
166 * intended to be displayed to the user for them to fix, prefer {@link getFriendlyFullName} instead.
167 *
168 * The full name contains the name of this reflection and the names of all parent reflections.
169 *
170 * @param separator Separator used to join the names of the reflections.
171 * @returns The full name of this reflection.
172 */
173 getFullName(separator?: string): string;
174 /**
175 * Return the full name of this reflection, with signature names dropped if possible without
176 * introducing ambiguity in the name.
177 */
178 getFriendlyFullName(): string;
179 /**
180 * Set a flag on this reflection.
181 */
182 setFlag(flag: ReflectionFlag, value?: boolean): void;
183 /**
184 * Has this reflection a visible comment?
185 *
186 * @returns TRUE when this reflection has a visible comment.
187 */
188 hasComment(): boolean;
189 hasGetterOrSetter(): boolean;
190 /**
191 * Return a child by its name.
192 *
193 * @param arg The name hierarchy of the child to look for.
194 * @returns The found child or undefined.
195 */
196 getChildByName(arg: string | string[]): Reflection | undefined;
197 /**
198 * Return whether this reflection is the root / project reflection.
199 */
200 isProject(): this is ProjectReflection;
201 isDeclaration(): this is DeclarationReflection;
202 isParameter(): this is ParameterReflection;
203 isDocument(): this is DocumentReflection;
204 isReference(): this is ReferenceReflection;
205 /**
206 * Check if this reflection or any of its parents have been marked with the `@deprecated` tag.
207 */
208 isDeprecated(): boolean;
209 /**
210 * Traverse most potential child reflections of this reflection.
211 *
212 * Note: This may not necessarily traverse child reflections contained within the `type` property
213 * of the reflection, and should not be relied on for this. Support for checking object types will likely be removed in v0.27.
214 *
215 * The given callback will be invoked for all children, signatures and type parameters
216 * attached to this reflection.
217 *
218 * @param callback The callback function that should be applied for each child reflection.
219 */
220 abstract traverse(callback: TraverseCallback): void;
221 visit(visitor: ReflectionVisitor): void;
222 /**
223 * Return a string representation of this reflection.
224 */
225 toString(): string;
226 /**
227 * Return a string representation of this reflection and all of its children.
228 *
229 * Note: This is intended as a debug tool only, output may change between patch versions.
230 *
231 * @param indent Used internally to indent child reflections.
232 */
233 toStringHierarchy(indent?: string): string;
234 toObject(serializer: Serializer): JSONOutput.Reflection;
235 fromObject(de: Deserializer, obj: JSONOutput.Reflection): void;
236}