X Tutup
Skip to content

Commit e792300

Browse files
octogonzoctogonz
authored
Merge pull request microsoft#1337 from rbuckton/deeplyLinkedtypes
[api-extractor] Deeply linked types
2 parents 64edc7d + d395618 commit e792300

File tree

58 files changed

+1809
-1565
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+1809
-1565
lines changed

‎apps/api-documenter/src/documenters/YamlDocumenter.ts‎

Lines changed: 205 additions & 115 deletions
Large diffs are not rendered by default.

‎apps/api-documenter/src/yaml/IYamlApiFile.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,19 @@ export interface IYamlParameter {
7373
* declared in a separate YAML file.
7474
*/
7575
export interface IYamlReference {
76+
uid?: string;
7677
name?: string;
78+
fullName?: string;
79+
'spec.typeScript'?: IYamlReferenceSpec[];
80+
}
81+
82+
/**
83+
* Part of the IYamlApiFile structure. Represents a text specification for a reference.
84+
*/
85+
export interface IYamlReferenceSpec {
7786
uid?: string;
87+
name?: string;
88+
fullName?: string;
7889
}
7990

8091
/**

‎apps/api-documenter/src/yaml/typescript.schema.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,11 +159,35 @@
159159
"type": "object",
160160
"additionalProperties": false,
161161
"properties": {
162+
"uid": {
163+
"type": "string"
164+
},
162165
"name": {
163166
"type": "string"
164167
},
168+
"fullName": {
169+
"type": "string"
170+
},
171+
"spec.typeScript": {
172+
"type": "array",
173+
"items": {
174+
"$ref": "#/definitions/spec"
175+
}
176+
}
177+
}
178+
},
179+
"spec": {
180+
"type": "object",
181+
"additionalProperties": false,
182+
"properties": {
165183
"uid": {
166184
"type": "string"
185+
},
186+
"name": {
187+
"type": "string"
188+
},
189+
"fullName": {
190+
"type": "string"
167191
}
168192
}
169193
},

‎apps/api-extractor-model/src/items/ApiDeclaredItem.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.s
33

4+
import { DeclarationReference } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
45
import { ApiDocumentedItem, IApiDocumentedItemJson, IApiDocumentedItemOptions } from './ApiDocumentedItem';
56
import { Excerpt, ExcerptToken, IExcerptTokenRange, IExcerptToken } from '../mixins/Excerpt';
67
import { DeserializerContext } from '../model/DeserializerContext';
@@ -47,7 +48,11 @@ export class ApiDeclaredItem extends ApiDocumentedItem {
4748
public constructor(options: IApiDeclaredItemOptions) {
4849
super(options);
4950

50-
this._excerptTokens = options.excerptTokens.map(x => new ExcerptToken(x.kind, x.text));
51+
this._excerptTokens = options.excerptTokens.map(x => {
52+
const canonicalReference: DeclarationReference | undefined = x.canonicalReference === undefined ? undefined :
53+
DeclarationReference.parse(x.canonicalReference);
54+
return new ExcerptToken(x.kind, x.text, canonicalReference);
55+
});
5156
this._excerpt = new Excerpt(this.excerptTokens, { startIndex: 0, endIndex: this.excerptTokens.length });
5257
}
5358

@@ -99,7 +104,13 @@ export class ApiDeclaredItem extends ApiDocumentedItem {
99104
/** @override */
100105
public serializeInto(jsonObject: Partial<IApiDeclaredItemJson>): void {
101106
super.serializeInto(jsonObject);
102-
jsonObject.excerptTokens = this.excerptTokens.map(x => ({ kind: x.kind, text: x.text }));
107+
jsonObject.excerptTokens = this.excerptTokens.map(x => {
108+
const excerptToken: IExcerptToken = { kind: x.kind, text: x.text };
109+
if (x.canonicalReference !== undefined) {
110+
excerptToken.canonicalReference = x.canonicalReference.toString();
111+
}
112+
return excerptToken;
113+
});
103114
}
104115

105116
/**

‎apps/api-extractor-model/src/mixins/Excerpt.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
22
// See LICENSE in the project root for license information.
33

4+
import { DeclarationReference } from '@microsoft/tsdoc/lib/beta/DeclarationReference';
45
import { Text } from '@microsoft/node-core-library';
56

67
/** @public */
@@ -21,20 +22,23 @@ export interface IExcerptTokenRange {
2122
export interface IExcerptToken {
2223
readonly kind: ExcerptTokenKind;
2324
text: string;
25+
canonicalReference?: string;
2426
}
2527

2628
/** @public */
2729
export class ExcerptToken {
2830
private readonly _kind: ExcerptTokenKind;
2931
private readonly _text: string;
32+
private readonly _canonicalReference: DeclarationReference | undefined;
3033

31-
public constructor(kind: ExcerptTokenKind, text: string) {
34+
public constructor(kind: ExcerptTokenKind, text: string, canonicalReference?: DeclarationReference) {
3235
this._kind = kind;
3336

3437
// Standardize the newlines across operating systems. Even though this may deviate from the actual
3538
// input source file that was parsed, it's useful because the newline gets serialized inside
3639
// a string literal in .api.json, which cannot be automatically normalized by Git.
3740
this._text = Text.convertToLf(text);
41+
this._canonicalReference = canonicalReference;
3842
}
3943

4044
public get kind(): ExcerptTokenKind {
@@ -44,6 +48,10 @@ export class ExcerptToken {
4448
public get text(): string {
4549
return this._text;
4650
}
51+
52+
public get canonicalReference(): DeclarationReference | undefined {
53+
return this._canonicalReference;
54+
}
4755
}
4856

4957
/**

‎apps/api-extractor/src/analyzer/AstSymbolTable.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -227,19 +227,17 @@ export class AstSymbolTable {
227227
* ```
228228
*/
229229
public static getLocalNameForSymbol(symbol: ts.Symbol): string {
230-
const symbolName: string = symbol.name;
231-
232230
// TypeScript binds well-known ECMAScript symbols like "[Symbol.iterator]" as "__@iterator".
233231
// Decode it back into "[Symbol.iterator]".
234-
const wellKnownSymbolName: string | undefined = TypeScriptHelpers.tryDecodeWellKnownSymbolName(symbolName);
232+
const wellKnownSymbolName: string | undefined = TypeScriptHelpers.tryDecodeWellKnownSymbolName(symbol.escapedName);
235233
if (wellKnownSymbolName) {
236234
return wellKnownSymbolName;
237235
}
238236

239-
const isUniqueSymbol: boolean = TypeScriptHelpers.isUniqueSymbolName(symbolName);
237+
const isUniqueSymbol: boolean = TypeScriptHelpers.isUniqueSymbolName(symbol.escapedName);
240238

241239
// We will try to obtain the name from a declaration; otherwise we'll fall back to the symbol name.
242-
let unquotedName: string = symbolName;
240+
let unquotedName: string = symbol.name;
243241

244242
for (const declaration of symbol.declarations || []) {
245243
// Handle cases such as "export default class X { }" where the symbol name is "default"

‎apps/api-extractor/src/analyzer/TypeScriptHelpers.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -222,8 +222,8 @@ export class TypeScriptHelpers {
222222
* If `name` is of this form, then `tryGetWellKnownSymbolName()` converts it back into e.g. `[Symbol.iterator]`.
223223
* If the string does not start with `__@` then `undefined` is returned.
224224
*/
225-
public static tryDecodeWellKnownSymbolName(name: string): string | undefined {
226-
const match: RegExpExecArray | null = TypeScriptHelpers._wellKnownSymbolNameRegExp.exec(name);
225+
public static tryDecodeWellKnownSymbolName(name: ts.__String): string | undefined {
226+
const match: RegExpExecArray | null = TypeScriptHelpers._wellKnownSymbolNameRegExp.exec(name as string);
227227
if (match) {
228228
const identifier: string = match[1];
229229
return `[Symbol.${identifier}]`;
@@ -238,8 +238,8 @@ export class TypeScriptHelpers {
238238
/**
239239
* Returns whether the provided name was generated for a TypeScript `unique symbol`.
240240
*/
241-
public static isUniqueSymbolName(name: string): boolean {
242-
return TypeScriptHelpers._uniqueSymbolNameRegExp.test(name);
241+
public static isUniqueSymbolName(name: ts.__String): boolean {
242+
return TypeScriptHelpers._uniqueSymbolNameRegExp.test(name as string);
243243
}
244244

245245
/**

‎apps/api-extractor/src/generators/ApiModelGenerator.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,16 +37,23 @@ import { Collector } from '../collector/Collector';
3737
import { AstDeclaration } from '../analyzer/AstDeclaration';
3838
import { ExcerptBuilder, IExcerptBuilderNodeToCapture } from './ExcerptBuilder';
3939
import { AstSymbol } from '../analyzer/AstSymbol';
40+
import { DeclarationReferenceGenerator } from './DeclarationReferenceGenerator';
4041

4142
export class ApiModelGenerator {
4243
private readonly _collector: Collector;
4344
private readonly _cachedOverloadIndexesByDeclaration: Map<AstDeclaration, number>;
4445
private readonly _apiModel: ApiModel;
46+
private readonly _referenceGenerator: DeclarationReferenceGenerator;
4547

4648
public constructor(collector: Collector) {
4749
this._collector = collector;
4850
this._cachedOverloadIndexesByDeclaration = new Map<AstDeclaration, number>();
4951
this._apiModel = new ApiModel();
52+
this._referenceGenerator = new DeclarationReferenceGenerator(
53+
collector.packageJsonLookup,
54+
collector.workingPackage.name,
55+
collector.program,
56+
collector.typeChecker);
5057
}
5158

5259
public get apiModel(): ApiModel {
@@ -195,6 +202,7 @@ export class ApiModelGenerator {
195202
const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, callSignature.parameters);
196203

197204
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
205+
referenceGenerator: this._referenceGenerator,
198206
startingNode: astDeclaration.declaration,
199207
nodesToCapture
200208
});
@@ -225,6 +233,7 @@ export class ApiModelGenerator {
225233
constructorDeclaration.parameters);
226234

227235
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
236+
referenceGenerator: this._referenceGenerator,
228237
startingNode: astDeclaration.declaration,
229238
nodesToCapture
230239
});
@@ -274,6 +283,7 @@ export class ApiModelGenerator {
274283
}
275284

276285
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
286+
referenceGenerator: this._referenceGenerator,
277287
startingNode: astDeclaration.declaration,
278288
stopBeforeChildKind: ts.SyntaxKind.FirstPunctuation, // FirstPunctuation = "{"
279289
nodesToCapture
@@ -314,6 +324,7 @@ export class ApiModelGenerator {
314324
const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, constructSignature.parameters);
315325

316326
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
327+
referenceGenerator: this._referenceGenerator,
317328
startingNode: astDeclaration.declaration,
318329
nodesToCapture
319330
});
@@ -337,6 +348,7 @@ export class ApiModelGenerator {
337348

338349
if (apiEnum === undefined) {
339350
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
351+
referenceGenerator: this._referenceGenerator,
340352
startingNode: astDeclaration.declaration,
341353
stopBeforeChildKind: ts.SyntaxKind.FirstPunctuation // FirstPunctuation = "{"
342354
});
@@ -368,6 +380,7 @@ export class ApiModelGenerator {
368380
nodesToCapture.push({ node: enumMember.initializer, tokenRange: initializerTokenRange });
369381

370382
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
383+
referenceGenerator: this._referenceGenerator,
371384
startingNode: astDeclaration.declaration,
372385
nodesToCapture
373386
});
@@ -408,6 +421,7 @@ export class ApiModelGenerator {
408421
functionDeclaration.parameters);
409422

410423
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
424+
referenceGenerator: this._referenceGenerator,
411425
startingNode: astDeclaration.declaration,
412426
nodesToCapture
413427
});
@@ -441,6 +455,7 @@ export class ApiModelGenerator {
441455
const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, indexSignature.parameters);
442456

443457
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
458+
referenceGenerator: this._referenceGenerator,
444459
startingNode: astDeclaration.declaration,
445460
nodesToCapture
446461
});
@@ -483,6 +498,7 @@ export class ApiModelGenerator {
483498
}
484499

485500
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
501+
referenceGenerator: this._referenceGenerator,
486502
startingNode: astDeclaration.declaration,
487503
stopBeforeChildKind: ts.SyntaxKind.FirstPunctuation, // FirstPunctuation = "{"
488504
nodesToCapture
@@ -525,6 +541,7 @@ export class ApiModelGenerator {
525541
const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, methodDeclaration.parameters);
526542

527543
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
544+
referenceGenerator: this._referenceGenerator,
528545
startingNode: astDeclaration.declaration,
529546
nodesToCapture
530547
});
@@ -564,6 +581,7 @@ export class ApiModelGenerator {
564581
const parameters: IApiParameterOptions[] = this._captureParameters(nodesToCapture, methodSignature.parameters);
565582

566583
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
584+
referenceGenerator: this._referenceGenerator,
567585
startingNode: astDeclaration.declaration,
568586
nodesToCapture
569587
});
@@ -587,6 +605,7 @@ export class ApiModelGenerator {
587605

588606
if (apiNamespace === undefined) {
589607
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
608+
referenceGenerator: this._referenceGenerator,
590609
startingNode: astDeclaration.declaration,
591610
stopBeforeChildKind: ts.SyntaxKind.ModuleBlock // ModuleBlock = the "{ ... }" block
592611
});
@@ -622,6 +641,7 @@ export class ApiModelGenerator {
622641
nodesToCapture.push({ node: propertyDeclaration.type, tokenRange: propertyTypeTokenRange });
623642

624643
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
644+
referenceGenerator: this._referenceGenerator,
625645
startingNode: astDeclaration.declaration,
626646
nodesToCapture
627647
});
@@ -654,6 +674,7 @@ export class ApiModelGenerator {
654674
nodesToCapture.push({ node: propertySignature.type, tokenRange: propertyTypeTokenRange });
655675

656676
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
677+
referenceGenerator: this._referenceGenerator,
657678
startingNode: astDeclaration.declaration,
658679
nodesToCapture
659680
});
@@ -691,6 +712,7 @@ export class ApiModelGenerator {
691712
nodesToCapture.push({ node: typeAliasDeclaration.type, tokenRange: typeTokenRange });
692713

693714
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
715+
referenceGenerator: this._referenceGenerator,
694716
startingNode: astDeclaration.declaration,
695717
nodesToCapture
696718
});
@@ -723,6 +745,7 @@ export class ApiModelGenerator {
723745
nodesToCapture.push({ node: variableDeclaration.type, tokenRange: variableTypeTokenRange });
724746

725747
const excerptTokens: IExcerptToken[] = ExcerptBuilder.build({
748+
referenceGenerator: this._referenceGenerator,
726749
startingNode: astDeclaration.declaration,
727750
nodesToCapture
728751
});

0 commit comments

Comments
 (0)
X Tutup