From 47a8fa7af903fb1d062615833970995b84aad0f6 Mon Sep 17 00:00:00 2001 From: Zack Elliott Date: Mon, 1 Aug 2022 18:26:54 -0700 Subject: [PATCH 1/6] Fix many bugs in DeclarationReferenceGenerator --- .../DeclarationReferenceGenerator.ts | 72 ++- .../config/build-config.json | 2 + .../api-extractor-scenarios.api.json | 248 ++++---- .../api-extractor-scenarios.api.md | 44 +- .../etc/apiItemKinds/rollup.d.ts | 39 +- .../api-extractor-scenarios.api.json | 598 ++++++++++++++++++ .../api-extractor-scenarios.api.md | 56 ++ .../declarationReferenceGenerator/rollup.d.ts | 35 + .../api-extractor-scenarios.api.json | 28 + .../api-extractor-scenarios.api.md | 3 + .../etc/mergedDeclarations/rollup.d.ts | 3 + .../api-extractor-scenarios.api.json | 281 ++++++++ .../api-extractor-scenarios.api.md | 21 + .../etc/typeLiterals/rollup.d.ts | 15 + .../src/apiItemKinds/classes.ts | 4 +- .../src/apiItemKinds/functions.ts | 5 + .../src/apiItemKinds/index.ts | 4 +- .../src/apiItemKinds/namespaces.ts | 14 + .../src/apiItemKinds/typeAliases.ts | 5 + .../src/apiItemKinds/variables.ts | 7 - .../declarationReferenceGenerator/index.ts | 53 ++ .../src/mergedDeclarations/index.ts | 5 + .../typeLiterals.ts => typeLiterals/index.ts} | 0 23 files changed, 1344 insertions(+), 198 deletions(-) create mode 100644 build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json create mode 100644 build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md create mode 100644 build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts create mode 100644 build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json create mode 100644 build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.md create mode 100644 build-tests/api-extractor-scenarios/etc/typeLiterals/rollup.d.ts create mode 100644 build-tests/api-extractor-scenarios/src/apiItemKinds/functions.ts create mode 100644 build-tests/api-extractor-scenarios/src/apiItemKinds/namespaces.ts create mode 100644 build-tests/api-extractor-scenarios/src/apiItemKinds/typeAliases.ts create mode 100644 build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts rename build-tests/api-extractor-scenarios/src/{apiItemKinds/typeLiterals.ts => typeLiterals/index.ts} (100%) diff --git a/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts b/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts index 690e0e8e898..4444351f975 100644 --- a/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts +++ b/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts @@ -230,10 +230,8 @@ export class DeclarationReferenceGenerator { if (!includeModuleSymbols) { return undefined; } - const sourceFile: ts.SourceFile | undefined = - followedSymbol.declarations && - followedSymbol.declarations[0] && - followedSymbol.declarations[0].getSourceFile(); + const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol); + const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile(); return new DeclarationReference(this._sourceFileToModuleSource(sourceFile)); } @@ -242,28 +240,8 @@ export class DeclarationReferenceGenerator { return undefined; } - const parent: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(followedSymbol); - let parentRef: DeclarationReference | undefined; - if (parent) { - parentRef = this._symbolToDeclarationReference( - parent, - ts.SymbolFlags.Namespace, - /*includeModuleSymbols*/ true - ); - } else { - // this may be a local symbol in a module... - const sourceFile: ts.SourceFile | undefined = - followedSymbol.declarations && - followedSymbol.declarations[0] && - followedSymbol.declarations[0].getSourceFile(); - if (sourceFile && ts.isExternalModule(sourceFile)) { - parentRef = new DeclarationReference(this._sourceFileToModuleSource(sourceFile)); - } else { - parentRef = new DeclarationReference(GlobalSource.instance); - } - } - - if (parentRef === undefined) { + const parentRef: DeclarationReference | undefined = this._getParentReference(followedSymbol); + if (!parentRef) { return undefined; } @@ -295,9 +273,6 @@ export class DeclarationReferenceGenerator { let navigation: Navigation | 'global' = DeclarationReferenceGenerator._getNavigationToSymbol(followedSymbol); if (navigation === 'global') { - if (parentRef.source !== GlobalSource.instance) { - parentRef = new DeclarationReference(GlobalSource.instance); - } navigation = Navigation.Exports; } @@ -306,6 +281,45 @@ export class DeclarationReferenceGenerator { .withMeaning(DeclarationReferenceGenerator._getMeaningOfSymbol(followedSymbol, meaning)); } + private _getParentReference(symbol: ts.Symbol): DeclarationReference | undefined { + let parentRef: DeclarationReference | undefined; + const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol); + + // First, try to find a parent symbol via the symbol tree. A parent symbol will exist if the + // symbol is part of a qualified name. For example, for `MyNamespace.MyClass`, `MyNamespace` + // is the parent symbol of `MyClass`. + let parentSymbol: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol); + + // If we failed to get a parent symbol, then try to find a parent symbol by its node. Is the node + // declared within a namespace? + if (!parentSymbol) { + const parentDeclaration: ts.Node | undefined = declaration?.parent?.parent; + if (parentDeclaration && ts.isModuleDeclaration(parentDeclaration)) { + parentSymbol = TypeScriptHelpers.getSymbolForDeclaration(parentDeclaration, this._typeChecker); + } + } + + // If there's still no parent symbol, then this symbol is either a top-level export from a package + // entry point or a global. Build the declaration reference accordingly. + if (!parentSymbol) { + const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile(); + if (sourceFile && ts.isExternalModule(sourceFile)) { + parentRef = new DeclarationReference(this._sourceFileToModuleSource(sourceFile)); + } else { + parentRef = new DeclarationReference(GlobalSource.instance); + } + } else { + // If there is a parent symbol, then build the declaration reference for that symbol. + parentRef = this._symbolToDeclarationReference( + parentSymbol, + parentSymbol.flags, + /*includeModuleSymbols*/ true + ); + } + + return parentRef; + } + private _getPackageName(sourceFile: ts.SourceFile): string { if (this._program.isSourceFileFromExternalLibrary(sourceFile)) { const packageJson: INodePackageJson | undefined = this._packageJsonLookup.tryLoadNodePackageJsonFor( diff --git a/build-tests/api-extractor-scenarios/config/build-config.json b/build-tests/api-extractor-scenarios/config/build-config.json index 927b69da27d..e4421e4c8e4 100644 --- a/build-tests/api-extractor-scenarios/config/build-config.json +++ b/build-tests/api-extractor-scenarios/config/build-config.json @@ -7,6 +7,7 @@ "bundledPackages", "circularImport", "circularImport2", + "declarationReferenceGenerator", "defaultExportOfEntryPoint", "defaultExportOfEntryPoint2", "defaultExportOfEntryPoint3", @@ -41,6 +42,7 @@ "preapproved", "readonlyDeclarations", "spanSorting", + "typeLiterals", "typeOf", "typeOf2", "typeOf3", diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json index 8de3dee8084..1c4d6a0aff3 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json @@ -219,109 +219,6 @@ ], "implementsTokenRanges": [] }, - { - "kind": "Class", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals:class", - "docComment": "/**\n * @public\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "export declare class ClassWithTypeLiterals " - } - ], - "releaseTag": "Public", - "name": "ClassWithTypeLiterals", - "preserveMemberOrder": false, - "members": [ - { - "kind": "Method", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals#method1:member(1)", - "docComment": "/**\n * type literal in\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "method1(vector: " - }, - { - "kind": "Content", - "text": "{\n x: number;\n y: number;\n }" - }, - { - "kind": "Content", - "text": "): " - }, - { - "kind": "Content", - "text": "void" - }, - { - "kind": "Content", - "text": ";" - } - ], - "isStatic": false, - "returnTypeTokenRange": { - "startIndex": 3, - "endIndex": 4 - }, - "releaseTag": "Public", - "isProtected": false, - "overloadIndex": 1, - "parameters": [ - { - "parameterName": "vector", - "parameterTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - }, - "isOptional": false - } - ], - "isOptional": false, - "name": "method1" - }, - { - "kind": "Method", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals#method2:member(1)", - "docComment": "/**\n * type literal output\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "method2(): " - }, - { - "kind": "Content", - "text": "{\n classValue: " - }, - { - "kind": "Reference", - "text": "ClassWithTypeLiterals", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals:class" - }, - { - "kind": "Content", - "text": ";\n callback: () => number;\n } | undefined" - }, - { - "kind": "Content", - "text": ";" - } - ], - "isStatic": false, - "returnTypeTokenRange": { - "startIndex": 1, - "endIndex": 4 - }, - "releaseTag": "Public", - "isProtected": false, - "overloadIndex": 1, - "parameters": [], - "isOptional": false, - "name": "method2" - } - ], - "implementsTokenRanges": [] - }, { "kind": "Variable", "canonicalReference": "api-extractor-scenarios!CONST_VARIABLE:var", @@ -469,61 +366,110 @@ }, { "kind": "Namespace", - "canonicalReference": "api-extractor-scenarios!NamespaceContainingVariable:namespace", + "canonicalReference": "api-extractor-scenarios!n1:namespace", "docComment": "/**\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", - "text": "export declare namespace NamespaceContainingVariable " + "text": "export declare namespace n1 " } ], "releaseTag": "Public", - "name": "NamespaceContainingVariable", + "name": "n1", "preserveMemberOrder": false, "members": [ { - "kind": "Variable", - "canonicalReference": "api-extractor-scenarios!NamespaceContainingVariable.constVariable:var", + "kind": "Namespace", + "canonicalReference": "api-extractor-scenarios!n1.n2:namespace", "docComment": "", "excerptTokens": [ { "kind": "Content", - "text": "constVariable: " - }, + "text": "export namespace n2 " + } + ], + "releaseTag": "Public", + "name": "n2", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.n2.SomeClass3:class", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "class SomeClass3 " + } + ], + "releaseTag": "Public", + "name": "SomeClass3", + "preserveMemberOrder": false, + "members": [], + "implementsTokenRanges": [] + } + ] + }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.SomeClass1:class", + "docComment": "", + "excerptTokens": [ { "kind": "Content", - "text": "object[]" + "text": "class SomeClass1 " } ], - "isReadonly": false, "releaseTag": "Public", - "name": "constVariable", - "variableTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - } + "name": "SomeClass1", + "preserveMemberOrder": false, + "members": [], + "implementsTokenRanges": [] }, { - "kind": "Variable", - "canonicalReference": "api-extractor-scenarios!NamespaceContainingVariable.variable:var", + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.SomeClass2:class", "docComment": "", "excerptTokens": [ { "kind": "Content", - "text": "variable: " + "text": "export class SomeClass2 extends " + }, + { + "kind": "Reference", + "text": "SomeClass1", + "canonicalReference": "api-extractor-scenarios!n1~SomeClass1:class" }, { "kind": "Content", - "text": "object[]" + "text": " " } ], - "isReadonly": false, "releaseTag": "Public", - "name": "variable", - "variableTypeTokenRange": { + "name": "SomeClass2", + "preserveMemberOrder": false, + "members": [], + "extendsTokenRange": { "startIndex": 1, "endIndex": 2 - } + }, + "implementsTokenRanges": [] + }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.SomeClass4:class", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "class SomeClass4 " + } + ], + "releaseTag": "Public", + "name": "SomeClass4", + "preserveMemberOrder": false, + "members": [], + "implementsTokenRanges": [] } ] }, @@ -846,6 +792,58 @@ ], "implementsTokenRanges": [] }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction:function(1)", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction(): " + }, + { + "kind": "Content", + "text": "void" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction" + }, + { + "kind": "TypeAlias", + "canonicalReference": "api-extractor-scenarios!SomeType:type", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare type SomeType = " + }, + { + "kind": "Content", + "text": "number" + }, + { + "kind": "Content", + "text": ";" + } + ], + "releaseTag": "Public", + "name": "SomeType", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + }, { "kind": "Variable", "canonicalReference": "api-extractor-scenarios!VARIABLE_WITHOUT_EXPLICIT_TYPE:var", diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md index ad066d8297c..d99e875147e 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md @@ -10,18 +10,6 @@ export abstract class AbstractClass { abstract member(): void; } -// @public (undocumented) -export class ClassWithTypeLiterals { - method1(vector: { - x: number; - y: number; - }): void; - method2(): { - classValue: ClassWithTypeLiterals; - callback: () => number; - } | undefined; -} - // @public (undocumented) export const CONST_VARIABLE: string; @@ -42,11 +30,27 @@ export interface IInterface { } // @public (undocumented) -export namespace NamespaceContainingVariable { - let // (undocumented) - variable: object[]; - let // (undocumented) - constVariable: object[]; +export namespace n1 { + // (undocumented) + export namespace n2 { + // (undocumented) + export class SomeClass3 { + } + } + // (undocumented) + export class SomeClass1 { + } + // (undocumented) + export class SomeClass2 extends SomeClass1 { + } + {}; +} + +// @public (undocumented) +export namespace n1 { + // (undocumented) + export class SomeClass4 { + } } // @public (undocumented) @@ -76,6 +80,12 @@ export class SimpleClass { set writeableProperty(value: string); } +// @public (undocumented) +export function someFunction(): void; + +// @public (undocumented) +export type SomeType = number; + // @public (undocumented) export const VARIABLE_WITHOUT_EXPLICIT_TYPE = "hello"; diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts index f196e577995..ee7918d3bcd 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts @@ -3,20 +3,6 @@ export declare abstract class AbstractClass { abstract member(): void; } -/** @public */ -export declare class ClassWithTypeLiterals { - /** type literal in */ - method1(vector: { - x: number; - y: number; - }): void; - /** type literal output */ - method2(): { - classValue: ClassWithTypeLiterals; - callback: () => number; - } | undefined; -} - /** @public */ export declare const CONST_VARIABLE: string; @@ -33,9 +19,22 @@ export declare interface IInterface { } /** @public */ -export declare namespace NamespaceContainingVariable { - let variable: object[]; - let constVariable: object[]; +export declare namespace n1 { + export class SomeClass1 { + } + export class SomeClass2 extends SomeClass1 { + } + export namespace n2 { + export class SomeClass3 { + } + } + {}; +} + +/** @public */ +export declare namespace n1 { + export class SomeClass4 { + } } /** @public */ @@ -68,6 +67,12 @@ export declare class SimpleClass { readonly someReadonlyPropWithType: number; } +/** @public */ +export declare function someFunction(): void; + +/** @public */ +export declare type SomeType = number; + /** @public */ export declare const VARIABLE_WITHOUT_EXPLICIT_TYPE = "hello"; diff --git a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json new file mode 100644 index 00000000000..d58b0d1dab7 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json @@ -0,0 +1,598 @@ +{ + "metadata": { + "toolPackage": "@microsoft/api-extractor", + "toolVersion": "[test mode]", + "schemaVersion": 1009, + "oldestForwardsCompatibleVersion": 1001, + "tsdocConfig": { + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "noStandardTags": true, + "tagDefinitions": [ + { + "tagName": "@alpha", + "syntaxKind": "modifier" + }, + { + "tagName": "@beta", + "syntaxKind": "modifier" + }, + { + "tagName": "@defaultValue", + "syntaxKind": "block" + }, + { + "tagName": "@decorator", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@deprecated", + "syntaxKind": "block" + }, + { + "tagName": "@eventProperty", + "syntaxKind": "modifier" + }, + { + "tagName": "@example", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@experimental", + "syntaxKind": "modifier" + }, + { + "tagName": "@inheritDoc", + "syntaxKind": "inline" + }, + { + "tagName": "@internal", + "syntaxKind": "modifier" + }, + { + "tagName": "@label", + "syntaxKind": "inline" + }, + { + "tagName": "@link", + "syntaxKind": "inline", + "allowMultiple": true + }, + { + "tagName": "@override", + "syntaxKind": "modifier" + }, + { + "tagName": "@packageDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@param", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@privateRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@public", + "syntaxKind": "modifier" + }, + { + "tagName": "@readonly", + "syntaxKind": "modifier" + }, + { + "tagName": "@remarks", + "syntaxKind": "block" + }, + { + "tagName": "@returns", + "syntaxKind": "block" + }, + { + "tagName": "@sealed", + "syntaxKind": "modifier" + }, + { + "tagName": "@see", + "syntaxKind": "block" + }, + { + "tagName": "@throws", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@typeParam", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@virtual", + "syntaxKind": "modifier" + }, + { + "tagName": "@betaDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@internalRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@preapproved", + "syntaxKind": "modifier" + } + ], + "supportForTags": { + "@alpha": true, + "@beta": true, + "@defaultValue": true, + "@decorator": true, + "@deprecated": true, + "@eventProperty": true, + "@example": true, + "@experimental": true, + "@inheritDoc": true, + "@internal": true, + "@label": true, + "@link": true, + "@override": true, + "@packageDocumentation": true, + "@param": true, + "@privateRemarks": true, + "@public": true, + "@readonly": true, + "@remarks": true, + "@returns": true, + "@sealed": true, + "@see": true, + "@throws": true, + "@typeParam": true, + "@virtual": true, + "@betaDocumentation": true, + "@internalRemarks": true, + "@preapproved": true + }, + "reportUnsupportedHtmlElements": false + } + }, + "kind": "Package", + "canonicalReference": "api-extractor-scenarios!", + "docComment": "", + "name": "api-extractor-scenarios", + "preserveMemberOrder": false, + "members": [ + { + "kind": "EntryPoint", + "canonicalReference": "api-extractor-scenarios!", + "name": "", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Namespace", + "canonicalReference": "api-extractor-scenarios!n1:namespace", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare namespace n1 " + } + ], + "releaseTag": "Public", + "name": "n1", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Namespace", + "canonicalReference": "api-extractor-scenarios!n1.n2:namespace", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "export namespace n2 " + } + ], + "releaseTag": "Public", + "name": "n2", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Namespace", + "canonicalReference": "api-extractor-scenarios!n1.n2.n3:namespace", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "namespace n3 " + } + ], + "releaseTag": "Public", + "name": "n3", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!n1.n2.n3.someFunction4:function(1)", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "function someFunction4(): " + }, + { + "kind": "Reference", + "text": "n2.n3.SomeType3", + "canonicalReference": "api-extractor-scenarios!n1.n2.n3.SomeType3:type" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction4" + }, + { + "kind": "TypeAlias", + "canonicalReference": "api-extractor-scenarios!n1.n2.n3.SomeType3:type", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "type SomeType3 = " + }, + { + "kind": "Content", + "text": "number" + }, + { + "kind": "Content", + "text": ";" + } + ], + "releaseTag": "Public", + "name": "SomeType3", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + } + ] + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!n1.n2.someFunction2:function(1)", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "function someFunction2(): " + }, + { + "kind": "Reference", + "text": "SomeType2", + "canonicalReference": "api-extractor-scenarios!n1.n2.SomeType2:type" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction2" + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!n1.n2.someFunction3:function(1)", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "function someFunction3(): " + }, + { + "kind": "Reference", + "text": "n2.SomeType2", + "canonicalReference": "api-extractor-scenarios!n1.n2.SomeType2:type" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction3" + }, + { + "kind": "TypeAlias", + "canonicalReference": "api-extractor-scenarios!n1.n2.SomeType2:type", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "type SomeType2 = " + }, + { + "kind": "Content", + "text": "number" + }, + { + "kind": "Content", + "text": ";" + } + ], + "releaseTag": "Public", + "name": "SomeType2", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + } + ] + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!n1.someFunction1:function(1)", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "export function someFunction1(): " + }, + { + "kind": "Reference", + "text": "SomeType1", + "canonicalReference": "api-extractor-scenarios!n1~SomeType1:type" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction1" + }, + { + "kind": "TypeAlias", + "canonicalReference": "api-extractor-scenarios!n1.SomeType1:type", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "type SomeType1 = " + }, + { + "kind": "Content", + "text": "number" + }, + { + "kind": "Content", + "text": ";" + } + ], + "releaseTag": "Public", + "name": "SomeType1", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + } + ] + }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!SomeClass:class", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare class SomeClass " + } + ], + "releaseTag": "Public", + "name": "SomeClass", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Property", + "canonicalReference": "api-extractor-scenarios!SomeClass.staticProp:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "static staticProp: " + }, + { + "kind": "Content", + "text": "number" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isReadonly": false, + "isOptional": false, + "releaseTag": "Public", + "name": "staticProp", + "propertyTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isStatic": true, + "isProtected": false + } + ], + "implementsTokenRanges": [] + }, + { + "kind": "Enum", + "canonicalReference": "api-extractor-scenarios!SomeEnum:enum", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare enum SomeEnum " + } + ], + "releaseTag": "Public", + "name": "SomeEnum", + "preserveMemberOrder": false, + "members": [ + { + "kind": "EnumMember", + "canonicalReference": "api-extractor-scenarios!SomeEnum.A:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "A = " + }, + { + "kind": "Content", + "text": "\"A\"" + } + ], + "initializerTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "name": "A" + }, + { + "kind": "EnumMember", + "canonicalReference": "api-extractor-scenarios!SomeEnum.B:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "B = " + }, + { + "kind": "Content", + "text": "\"B\"" + } + ], + "initializerTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "name": "B" + }, + { + "kind": "EnumMember", + "canonicalReference": "api-extractor-scenarios!SomeEnum.C:member", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "C = " + }, + { + "kind": "Content", + "text": "\"C\"" + } + ], + "initializerTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "name": "C" + } + ] + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction5:function(1)", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction5(): " + }, + { + "kind": "Reference", + "text": "SomeEnum.A", + "canonicalReference": "api-extractor-scenarios!SomeEnum.A:member" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction5" + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction6:function(1)", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction6(): " + }, + { + "kind": "Content", + "text": "typeof " + }, + { + "kind": "Reference", + "text": "SomeClass.staticProp", + "canonicalReference": "api-extractor-scenarios!SomeClass.staticProp:member" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 3 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction6" + } + ] + } + ] +} diff --git a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md new file mode 100644 index 00000000000..20e7c87f8a5 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md @@ -0,0 +1,56 @@ +## API Report File for "api-extractor-scenarios" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +// @public (undocumented) +export namespace n1 { + // (undocumented) + export namespace n2 { + // (undocumented) + export namespace n3 { + // (undocumented) + export function someFunction4(): n2.n3.SomeType3; + // (undocumented) + export type SomeType3 = number; + } + // (undocumented) + export function someFunction2(): SomeType2; + // (undocumented) + export function someFunction3(): n2.SomeType2; + // (undocumented) + export type SomeType2 = number; + } + // (undocumented) + export function someFunction1(): SomeType1; + // (undocumented) + export type SomeType1 = number; + {}; +} + +// @public (undocumented) +export class SomeClass { + // (undocumented) + static staticProp: number; +} + +// @public (undocumented) +export enum SomeEnum { + // (undocumented) + A = "A", + // (undocumented) + B = "B", + // (undocumented) + C = "C" +} + +// @public (undocumented) +export function someFunction5(): SomeEnum.A; + +// @public (undocumented) +export function someFunction6(): typeof SomeClass.staticProp; + +// (No @packageDocumentation comment for this package) + +``` diff --git a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts new file mode 100644 index 00000000000..f399de25053 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts @@ -0,0 +1,35 @@ +/** @public */ +export declare namespace n1 { + export type SomeType1 = number; + export function someFunction1(): SomeType1; + export namespace n2 { + export type SomeType2 = number; + export function someFunction2(): SomeType2; + export function someFunction3(): n2.SomeType2; + export namespace n3 { + export type SomeType3 = number; + export function someFunction4(): n2.n3.SomeType3; + } + } + {}; +} + +/** @public */ +export declare class SomeClass { + static staticProp: number; +} + +/** @public */ +export declare enum SomeEnum { + A = "A", + B = "B", + C = "C" +} + +/** @public */ +export declare function someFunction5(): SomeEnum.A; + +/** @public */ +export declare function someFunction6(): typeof SomeClass.staticProp; + +export { } diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json index f79add87f66..f8400c5577a 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json @@ -434,6 +434,34 @@ } ], "extendsTokenRanges": [] + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction:function(1)", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction(): " + }, + { + "kind": "Reference", + "text": "MergedClassAndInterface", + "canonicalReference": "api-extractor-scenarios!MergedClassAndInterface:class" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction" } ] } diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md index 86cdc9e8e33..fa16cea4f17 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md @@ -42,6 +42,9 @@ export interface MergedInterfaces { someProp: number; } +// @public (undocumented) +export function someFunction(): MergedClassAndInterface; + // (No @packageDocumentation comment for this package) ``` diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts index 426076798ca..d557a24d0d1 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts @@ -29,4 +29,7 @@ export declare interface MergedInterfaces { someProp: number; } +/** @public */ +export declare function someFunction(): MergedClassAndInterface; + export { } diff --git a/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json new file mode 100644 index 00000000000..bf6587a6a6e --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.json @@ -0,0 +1,281 @@ +{ + "metadata": { + "toolPackage": "@microsoft/api-extractor", + "toolVersion": "[test mode]", + "schemaVersion": 1009, + "oldestForwardsCompatibleVersion": 1001, + "tsdocConfig": { + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "noStandardTags": true, + "tagDefinitions": [ + { + "tagName": "@alpha", + "syntaxKind": "modifier" + }, + { + "tagName": "@beta", + "syntaxKind": "modifier" + }, + { + "tagName": "@defaultValue", + "syntaxKind": "block" + }, + { + "tagName": "@decorator", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@deprecated", + "syntaxKind": "block" + }, + { + "tagName": "@eventProperty", + "syntaxKind": "modifier" + }, + { + "tagName": "@example", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@experimental", + "syntaxKind": "modifier" + }, + { + "tagName": "@inheritDoc", + "syntaxKind": "inline" + }, + { + "tagName": "@internal", + "syntaxKind": "modifier" + }, + { + "tagName": "@label", + "syntaxKind": "inline" + }, + { + "tagName": "@link", + "syntaxKind": "inline", + "allowMultiple": true + }, + { + "tagName": "@override", + "syntaxKind": "modifier" + }, + { + "tagName": "@packageDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@param", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@privateRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@public", + "syntaxKind": "modifier" + }, + { + "tagName": "@readonly", + "syntaxKind": "modifier" + }, + { + "tagName": "@remarks", + "syntaxKind": "block" + }, + { + "tagName": "@returns", + "syntaxKind": "block" + }, + { + "tagName": "@sealed", + "syntaxKind": "modifier" + }, + { + "tagName": "@see", + "syntaxKind": "block" + }, + { + "tagName": "@throws", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@typeParam", + "syntaxKind": "block", + "allowMultiple": true + }, + { + "tagName": "@virtual", + "syntaxKind": "modifier" + }, + { + "tagName": "@betaDocumentation", + "syntaxKind": "modifier" + }, + { + "tagName": "@internalRemarks", + "syntaxKind": "block" + }, + { + "tagName": "@preapproved", + "syntaxKind": "modifier" + } + ], + "supportForTags": { + "@alpha": true, + "@beta": true, + "@defaultValue": true, + "@decorator": true, + "@deprecated": true, + "@eventProperty": true, + "@example": true, + "@experimental": true, + "@inheritDoc": true, + "@internal": true, + "@label": true, + "@link": true, + "@override": true, + "@packageDocumentation": true, + "@param": true, + "@privateRemarks": true, + "@public": true, + "@readonly": true, + "@remarks": true, + "@returns": true, + "@sealed": true, + "@see": true, + "@throws": true, + "@typeParam": true, + "@virtual": true, + "@betaDocumentation": true, + "@internalRemarks": true, + "@preapproved": true + }, + "reportUnsupportedHtmlElements": false + } + }, + "kind": "Package", + "canonicalReference": "api-extractor-scenarios!", + "docComment": "", + "name": "api-extractor-scenarios", + "preserveMemberOrder": false, + "members": [ + { + "kind": "EntryPoint", + "canonicalReference": "api-extractor-scenarios!", + "name": "", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals:class", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare class ClassWithTypeLiterals " + } + ], + "releaseTag": "Public", + "name": "ClassWithTypeLiterals", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Method", + "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals#method1:member(1)", + "docComment": "/**\n * type literal in\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "method1(vector: " + }, + { + "kind": "Content", + "text": "{\n x: number;\n y: number;\n }" + }, + { + "kind": "Content", + "text": "): " + }, + { + "kind": "Content", + "text": "void" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isStatic": false, + "returnTypeTokenRange": { + "startIndex": 3, + "endIndex": 4 + }, + "releaseTag": "Public", + "isProtected": false, + "overloadIndex": 1, + "parameters": [ + { + "parameterName": "vector", + "parameterTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "isOptional": false + } + ], + "isOptional": false, + "name": "method1" + }, + { + "kind": "Method", + "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals#method2:member(1)", + "docComment": "/**\n * type literal output\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "method2(): " + }, + { + "kind": "Content", + "text": "{\n classValue: " + }, + { + "kind": "Reference", + "text": "ClassWithTypeLiterals", + "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals:class" + }, + { + "kind": "Content", + "text": ";\n callback: () => number;\n } | undefined" + }, + { + "kind": "Content", + "text": ";" + } + ], + "isStatic": false, + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 4 + }, + "releaseTag": "Public", + "isProtected": false, + "overloadIndex": 1, + "parameters": [], + "isOptional": false, + "name": "method2" + } + ], + "implementsTokenRanges": [] + } + ] + } + ] +} diff --git a/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.md new file mode 100644 index 00000000000..ca50c2b171c --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/typeLiterals/api-extractor-scenarios.api.md @@ -0,0 +1,21 @@ +## API Report File for "api-extractor-scenarios" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +// @public (undocumented) +export class ClassWithTypeLiterals { + method1(vector: { + x: number; + y: number; + }): void; + method2(): { + classValue: ClassWithTypeLiterals; + callback: () => number; + } | undefined; +} + +// (No @packageDocumentation comment for this package) + +``` diff --git a/build-tests/api-extractor-scenarios/etc/typeLiterals/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/typeLiterals/rollup.d.ts new file mode 100644 index 00000000000..0c3cecaa513 --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/typeLiterals/rollup.d.ts @@ -0,0 +1,15 @@ +/** @public */ +export declare class ClassWithTypeLiterals { + /** type literal in */ + method1(vector: { + x: number; + y: number; + }): void; + /** type literal output */ + method2(): { + classValue: ClassWithTypeLiterals; + callback: () => number; + } | undefined; +} + +export { } diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/classes.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/classes.ts index 57ab7b981c2..d8359362ea0 100644 --- a/build-tests/api-extractor-scenarios/src/apiItemKinds/classes.ts +++ b/build-tests/api-extractor-scenarios/src/apiItemKinds/classes.ts @@ -21,6 +21,6 @@ export class SimpleClass { } public set writeableProperty(value: string) {} - readonly someReadonlyProp = 5; - readonly someReadonlyPropWithType: number = 5; + public readonly someReadonlyProp = 5; + public readonly someReadonlyPropWithType: number = 5; } diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/functions.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/functions.ts new file mode 100644 index 00000000000..729f8daa908 --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/apiItemKinds/functions.ts @@ -0,0 +1,5 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +/** @public */ +export function someFunction(): void {} diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/index.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/index.ts index cc5a0f21ba2..a380574a7e0 100644 --- a/build-tests/api-extractor-scenarios/src/apiItemKinds/index.ts +++ b/build-tests/api-extractor-scenarios/src/apiItemKinds/index.ts @@ -3,6 +3,8 @@ export * from './classes'; export * from './enums'; +export * from './functions'; export * from './interfaces'; -export * from './typeLiterals'; +export * from './namespaces'; +export * from './typeAliases'; export * from './variables'; diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/namespaces.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/namespaces.ts new file mode 100644 index 00000000000..33513d36b1f --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/apiItemKinds/namespaces.ts @@ -0,0 +1,14 @@ +/** @public */ +export namespace n1 { + class SomeClass1 {} + export class SomeClass2 extends SomeClass1 {} + + export namespace n2 { + export class SomeClass3 {} + } +} + +/** @public */ +export namespace n1 { + export class SomeClass4 {} +} diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/typeAliases.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/typeAliases.ts new file mode 100644 index 00000000000..4bbe90eb1de --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/apiItemKinds/typeAliases.ts @@ -0,0 +1,5 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +/** @public */ +export type SomeType = number; diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/variables.ts b/build-tests/api-extractor-scenarios/src/apiItemKinds/variables.ts index 05f472df886..af31c7aa2cc 100644 --- a/build-tests/api-extractor-scenarios/src/apiItemKinds/variables.ts +++ b/build-tests/api-extractor-scenarios/src/apiItemKinds/variables.ts @@ -9,10 +9,3 @@ export let nonConstVariable: string = 'hello'; /** @public */ export const VARIABLE_WITHOUT_EXPLICIT_TYPE = 'hello'; - -/** @public */ -export namespace NamespaceContainingVariable { - export let variable: object[] = []; - - export let constVariable: object[] = []; -} diff --git a/build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts b/build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts new file mode 100644 index 00000000000..e8ebc362d12 --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts @@ -0,0 +1,53 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +/** @public */ +export namespace n1 { + type SomeType1 = number; + + export function someFunction1(): SomeType1 { + return 5; + } + + export namespace n2 { + export type SomeType2 = number; + + export function someFunction2(): SomeType2 { + return 5; + } + + export function someFunction3(): n2.SomeType2 { + return 5; + } + + export namespace n3 { + export type SomeType3 = number; + + export function someFunction4(): n2.n3.SomeType3 { + return 5; + } + } + } +} + +/** @public */ +export enum SomeEnum { + A = 'A', + B = 'B', + C = 'C' +} + +/** @public */ +export function someFunction5(): SomeEnum.A { + return SomeEnum.A; +} + +/** @public */ +export class SomeClass { + public static staticProp = 5; +} + +/** @public */ +export function someFunction6(): typeof SomeClass.staticProp { + return 5; +} diff --git a/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts b/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts index 40ac8801c21..77d19957df3 100644 --- a/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts +++ b/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts @@ -32,3 +32,8 @@ export class MergedClassAndNamespace { export namespace MergedClassAndNamespace { export let anotherProp: number; } + +/** @public */ +export function someFunction(): MergedClassAndInterface { + return new MergedClassAndInterface(); +} diff --git a/build-tests/api-extractor-scenarios/src/apiItemKinds/typeLiterals.ts b/build-tests/api-extractor-scenarios/src/typeLiterals/index.ts similarity index 100% rename from build-tests/api-extractor-scenarios/src/apiItemKinds/typeLiterals.ts rename to build-tests/api-extractor-scenarios/src/typeLiterals/index.ts From ad86ef3d84e21c8ab929036d9a7a14e191ce4682 Mon Sep 17 00:00:00 2001 From: Zack Elliott Date: Tue, 2 Aug 2022 08:05:59 -0700 Subject: [PATCH 2/6] Bit more work on the declaration reference generator changes --- .../DeclarationReferenceGenerator.ts | 73 +++++---- .../config/build-config.json | 2 +- .../declarationReferenceGenerator/rollup.d.ts | 35 ----- .../api-extractor-scenarios.api.json | 147 +++++++++++++----- .../api-extractor-scenarios.api.md | 29 +++- .../etc/referenceTokens/rollup.d.ts | 68 ++++++++ .../etc/typeOf3/rollup.d.ts | 4 +- .../declarationReferenceGenerator/index.ts | 53 ------- .../src/referenceTokens/index.ts | 88 +++++++++++ .../src/typeOf3/index.ts | 4 +- .../workspace/common/pnpm-lock.yaml | 14 +- 11 files changed, 337 insertions(+), 180 deletions(-) delete mode 100644 build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts rename build-tests/api-extractor-scenarios/etc/{declarationReferenceGenerator => referenceTokens}/api-extractor-scenarios.api.json (82%) rename build-tests/api-extractor-scenarios/etc/{declarationReferenceGenerator => referenceTokens}/api-extractor-scenarios.api.md (65%) create mode 100644 build-tests/api-extractor-scenarios/etc/referenceTokens/rollup.d.ts delete mode 100644 build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts create mode 100644 build-tests/api-extractor-scenarios/src/referenceTokens/index.ts diff --git a/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts b/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts index 4444351f975..0855dfba7c5 100644 --- a/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts +++ b/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts @@ -240,7 +240,7 @@ export class DeclarationReferenceGenerator { return undefined; } - const parentRef: DeclarationReference | undefined = this._getParentReference(followedSymbol); + let parentRef: DeclarationReference | undefined = this._getParentReference(followedSymbol); if (!parentRef) { return undefined; } @@ -273,6 +273,9 @@ export class DeclarationReferenceGenerator { let navigation: Navigation | 'global' = DeclarationReferenceGenerator._getNavigationToSymbol(followedSymbol); if (navigation === 'global') { + if (parentRef.source !== GlobalSource.instance) { + parentRef = new DeclarationReference(GlobalSource.instance); + } navigation = Navigation.Exports; } @@ -282,42 +285,54 @@ export class DeclarationReferenceGenerator { } private _getParentReference(symbol: ts.Symbol): DeclarationReference | undefined { - let parentRef: DeclarationReference | undefined; const declaration: ts.Node | undefined = TypeScriptHelpers.tryGetADeclaration(symbol); - // First, try to find a parent symbol via the symbol tree. A parent symbol will exist if the - // symbol is part of a qualified name. For example, for `MyNamespace.MyClass`, `MyNamespace` - // is the parent symbol of `MyClass`. - let parentSymbol: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol); - - // If we failed to get a parent symbol, then try to find a parent symbol by its node. Is the node - // declared within a namespace? - if (!parentSymbol) { - const parentDeclaration: ts.Node | undefined = declaration?.parent?.parent; - if (parentDeclaration && ts.isModuleDeclaration(parentDeclaration)) { - parentSymbol = TypeScriptHelpers.getSymbolForDeclaration(parentDeclaration, this._typeChecker); - } - } - - // If there's still no parent symbol, then this symbol is either a top-level export from a package - // entry point or a global. Build the declaration reference accordingly. - if (!parentSymbol) { - const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile(); - if (sourceFile && ts.isExternalModule(sourceFile)) { - parentRef = new DeclarationReference(this._sourceFileToModuleSource(sourceFile)); - } else { - parentRef = new DeclarationReference(GlobalSource.instance); - } - } else { - // If there is a parent symbol, then build the declaration reference for that symbol. - parentRef = this._symbolToDeclarationReference( + // First, try to find a parent symbol via the symbol tree. + const parentSymbol: ts.Symbol | undefined = TypeScriptInternals.getSymbolParent(symbol); + if (parentSymbol) { + return this._symbolToDeclarationReference( parentSymbol, parentSymbol.flags, /*includeModuleSymbols*/ true ); } - return parentRef; + // If that doesn't work, try to find a parent symbol via the node tree. As far as we can tell, + // this logic is only needed for local symbols within namespaces. For example: + // + // ``` + // export namespace n { + // type SomeType = number; + // export function someFunction(): SomeType { return 5; } + // } + // ``` + // + // In the example above, `SomeType` doesn't have a parent symbol per the TS internal API above, + // but its reference still needs to be qualified with the parent reference for `n`. + const grandParent: ts.Node | undefined = declaration?.parent?.parent; + if (grandParent && ts.isModuleDeclaration(grandParent)) { + const grandParentSymbol: ts.Symbol | undefined = TypeScriptInternals.tryGetSymbolForDeclaration( + grandParent, + this._typeChecker + ); + if (grandParentSymbol) { + return this._symbolToDeclarationReference( + grandParentSymbol, + grandParentSymbol.flags, + /*includeModuleSymbols*/ true + ); + } + } + + // At this point, we either have... + const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile(); + if (sourceFile && ts.isExternalModule(sourceFile)) { + // ...a local symbol in some source file module. + return new DeclarationReference(this._sourceFileToModuleSource(sourceFile)); + } else { + // ...a global symbol. + return new DeclarationReference(GlobalSource.instance); + } } private _getPackageName(sourceFile: ts.SourceFile): string { diff --git a/build-tests/api-extractor-scenarios/config/build-config.json b/build-tests/api-extractor-scenarios/config/build-config.json index e4421e4c8e4..b1c0327f4e7 100644 --- a/build-tests/api-extractor-scenarios/config/build-config.json +++ b/build-tests/api-extractor-scenarios/config/build-config.json @@ -7,7 +7,6 @@ "bundledPackages", "circularImport", "circularImport2", - "declarationReferenceGenerator", "defaultExportOfEntryPoint", "defaultExportOfEntryPoint2", "defaultExportOfEntryPoint3", @@ -41,6 +40,7 @@ "namedDefaultImport", "preapproved", "readonlyDeclarations", + "referenceTokens", "spanSorting", "typeLiterals", "typeOf", diff --git a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts deleted file mode 100644 index f399de25053..00000000000 --- a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/rollup.d.ts +++ /dev/null @@ -1,35 +0,0 @@ -/** @public */ -export declare namespace n1 { - export type SomeType1 = number; - export function someFunction1(): SomeType1; - export namespace n2 { - export type SomeType2 = number; - export function someFunction2(): SomeType2; - export function someFunction3(): n2.SomeType2; - export namespace n3 { - export type SomeType3 = number; - export function someFunction4(): n2.n3.SomeType3; - } - } - {}; -} - -/** @public */ -export declare class SomeClass { - static staticProp: number; -} - -/** @public */ -export declare enum SomeEnum { - A = "A", - B = "B", - C = "C" -} - -/** @public */ -export declare function someFunction5(): SomeEnum.A; - -/** @public */ -export declare function someFunction6(): typeof SomeClass.staticProp; - -export { } diff --git a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json similarity index 82% rename from build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json rename to build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json index d58b0d1dab7..cb43f150764 100644 --- a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.json @@ -175,7 +175,7 @@ { "kind": "Namespace", "canonicalReference": "api-extractor-scenarios!n1:namespace", - "docComment": "/**\n * @public\n */\n", + "docComment": "/**\n * Various namespace scenarios.\n *\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", @@ -207,7 +207,7 @@ "excerptTokens": [ { "kind": "Content", - "text": "namespace n3 " + "text": "export namespace n3 " } ], "releaseTag": "Public", @@ -216,12 +216,12 @@ "members": [ { "kind": "Function", - "canonicalReference": "api-extractor-scenarios!n1.n2.n3.someFunction4:function(1)", + "canonicalReference": "api-extractor-scenarios!n1.n2.n3.someFunction3:function(1)", "docComment": "", "excerptTokens": [ { "kind": "Content", - "text": "function someFunction4(): " + "text": "function someFunction3(): " }, { "kind": "Reference", @@ -240,7 +240,7 @@ "releaseTag": "Public", "overloadIndex": 1, "parameters": [], - "name": "someFunction4" + "name": "someFunction3" }, { "kind": "TypeAlias", @@ -276,12 +276,12 @@ "excerptTokens": [ { "kind": "Content", - "text": "function someFunction2(): " + "text": "export function someFunction2(): " }, { "kind": "Reference", "text": "SomeType2", - "canonicalReference": "api-extractor-scenarios!n1.n2.SomeType2:type" + "canonicalReference": "api-extractor-scenarios!n1.n2~SomeType2:type" }, { "kind": "Content", @@ -297,34 +297,6 @@ "parameters": [], "name": "someFunction2" }, - { - "kind": "Function", - "canonicalReference": "api-extractor-scenarios!n1.n2.someFunction3:function(1)", - "docComment": "", - "excerptTokens": [ - { - "kind": "Content", - "text": "function someFunction3(): " - }, - { - "kind": "Reference", - "text": "n2.SomeType2", - "canonicalReference": "api-extractor-scenarios!n1.n2.SomeType2:type" - }, - { - "kind": "Content", - "text": ";" - } - ], - "returnTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - }, - "releaseTag": "Public", - "overloadIndex": 1, - "parameters": [], - "name": "someFunction3" - }, { "kind": "TypeAlias", "canonicalReference": "api-extractor-scenarios!n1.n2.SomeType2:type", @@ -409,21 +381,21 @@ }, { "kind": "Class", - "canonicalReference": "api-extractor-scenarios!SomeClass:class", + "canonicalReference": "api-extractor-scenarios!SomeClass1:class", "docComment": "/**\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", - "text": "export declare class SomeClass " + "text": "export declare class SomeClass1 " } ], "releaseTag": "Public", - "name": "SomeClass", + "name": "SomeClass1", "preserveMemberOrder": false, "members": [ { "kind": "Property", - "canonicalReference": "api-extractor-scenarios!SomeClass.staticProp:member", + "canonicalReference": "api-extractor-scenarios!SomeClass1.staticProp:member", "docComment": "", "excerptTokens": [ { @@ -453,6 +425,35 @@ ], "implementsTokenRanges": [] }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!SomeClass3:class", + "docComment": "/**\n * Unexported symbol reference.\n *\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare class SomeClass3 extends " + }, + { + "kind": "Reference", + "text": "SomeClass2", + "canonicalReference": "api-extractor-scenarios!~SomeClass2:class" + }, + { + "kind": "Content", + "text": " " + } + ], + "releaseTag": "Public", + "name": "SomeClass3", + "preserveMemberOrder": false, + "members": [], + "extendsTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "implementsTokenRanges": [] + }, { "kind": "Enum", "canonicalReference": "api-extractor-scenarios!SomeEnum:enum", @@ -535,7 +536,7 @@ { "kind": "Function", "canonicalReference": "api-extractor-scenarios!someFunction5:function(1)", - "docComment": "/**\n * @public\n */\n", + "docComment": "/**\n * Enum member reference.\n *\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", @@ -563,7 +564,7 @@ { "kind": "Function", "canonicalReference": "api-extractor-scenarios!someFunction6:function(1)", - "docComment": "/**\n * @public\n */\n", + "docComment": "/**\n * Static class member reference.\n *\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", @@ -575,8 +576,8 @@ }, { "kind": "Reference", - "text": "SomeClass.staticProp", - "canonicalReference": "api-extractor-scenarios!SomeClass.staticProp:member" + "text": "SomeClass1.staticProp", + "canonicalReference": "api-extractor-scenarios!SomeClass1.staticProp:member" }, { "kind": "Content", @@ -591,6 +592,66 @@ "overloadIndex": 1, "parameters": [], "name": "someFunction6" + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction7:function(1)", + "docComment": "/**\n * Global symbol reference.\n *\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction7(): " + }, + { + "kind": "Reference", + "text": "Promise", + "canonicalReference": "!Promise:interface" + }, + { + "kind": "Content", + "text": "" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 3 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction7" + }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction8:function(1)", + "docComment": "/**\n * External symbol reference.\n *\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction8(): " + }, + { + "kind": "Reference", + "text": "Lib2Class", + "canonicalReference": "api-extractor-lib2-test!Lib2Class:class" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction8" } ] } diff --git a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.md similarity index 65% rename from build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md rename to build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.md index 20e7c87f8a5..1f9c9929712 100644 --- a/build-tests/api-extractor-scenarios/etc/declarationReferenceGenerator/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/referenceTokens/api-extractor-scenarios.api.md @@ -4,23 +4,24 @@ ```ts -// @public (undocumented) +import { Lib2Class } from 'api-extractor-lib2-test'; + +// @public export namespace n1 { // (undocumented) export namespace n2 { // (undocumented) export namespace n3 { // (undocumented) - export function someFunction4(): n2.n3.SomeType3; + export function someFunction3(): n2.n3.SomeType3; // (undocumented) export type SomeType3 = number; } // (undocumented) export function someFunction2(): SomeType2; // (undocumented) - export function someFunction3(): n2.SomeType2; - // (undocumented) export type SomeType2 = number; + {}; } // (undocumented) export function someFunction1(): SomeType1; @@ -30,11 +31,17 @@ export namespace n1 { } // @public (undocumented) -export class SomeClass { +export class SomeClass1 { // (undocumented) static staticProp: number; } +// Warning: (ae-forgotten-export) The symbol "SomeClass2" needs to be exported by the entry point index.d.ts +// +// @public +export class SomeClass3 extends SomeClass2 { +} + // @public (undocumented) export enum SomeEnum { // (undocumented) @@ -45,11 +52,17 @@ export enum SomeEnum { C = "C" } -// @public (undocumented) +// @public export function someFunction5(): SomeEnum.A; -// @public (undocumented) -export function someFunction6(): typeof SomeClass.staticProp; +// @public +export function someFunction6(): typeof SomeClass1.staticProp; + +// @public +export function someFunction7(): Promise; + +// @public +export function someFunction8(): Lib2Class; // (No @packageDocumentation comment for this package) diff --git a/build-tests/api-extractor-scenarios/etc/referenceTokens/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/referenceTokens/rollup.d.ts new file mode 100644 index 00000000000..f27d291c0ad --- /dev/null +++ b/build-tests/api-extractor-scenarios/etc/referenceTokens/rollup.d.ts @@ -0,0 +1,68 @@ +import { Lib2Class } from 'api-extractor-lib2-test'; + +/** + * Various namespace scenarios. + * @public + */ +export declare namespace n1 { + export type SomeType1 = number; + export function someFunction1(): SomeType1; + export namespace n2 { + export type SomeType2 = number; + export function someFunction2(): SomeType2; + export namespace n3 { + export type SomeType3 = number; + export function someFunction3(): n2.n3.SomeType3; + } + {}; + } + {}; +} + +/** @public */ +export declare class SomeClass1 { + static staticProp: number; +} + +declare class SomeClass2 { +} + +/** + * Unexported symbol reference. + * @public + */ +export declare class SomeClass3 extends SomeClass2 { +} + +/** @public */ +export declare enum SomeEnum { + A = "A", + B = "B", + C = "C" +} + +/** + * Enum member reference. + * @public + */ +export declare function someFunction5(): SomeEnum.A; + +/** + * Static class member reference. + * @public + */ +export declare function someFunction6(): typeof SomeClass1.staticProp; + +/** + * Global symbol reference. + * @public + */ +export declare function someFunction7(): Promise; + +/** + * External symbol reference. + * @public + */ +export declare function someFunction8(): Lib2Class; + +export { } diff --git a/build-tests/api-extractor-scenarios/etc/typeOf3/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/typeOf3/rollup.d.ts index 1c69e15110b..6b25c9962b0 100644 --- a/build-tests/api-extractor-scenarios/etc/typeOf3/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/typeOf3/rollup.d.ts @@ -5,13 +5,13 @@ export declare function f1(x: number): typeof x; /** - * A function that indirectly references its own parameter type. + * A function that indirectly references its own parameter type. * @public */ export declare function f2(x: number): keyof typeof x; /** - * A function that references its own type. + * A function that references its own type. * @public */ export declare function f3(): typeof f3 | undefined; diff --git a/build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts b/build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts deleted file mode 100644 index e8ebc362d12..00000000000 --- a/build-tests/api-extractor-scenarios/src/declarationReferenceGenerator/index.ts +++ /dev/null @@ -1,53 +0,0 @@ -// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. -// See LICENSE in the project root for license information. - -/** @public */ -export namespace n1 { - type SomeType1 = number; - - export function someFunction1(): SomeType1 { - return 5; - } - - export namespace n2 { - export type SomeType2 = number; - - export function someFunction2(): SomeType2 { - return 5; - } - - export function someFunction3(): n2.SomeType2 { - return 5; - } - - export namespace n3 { - export type SomeType3 = number; - - export function someFunction4(): n2.n3.SomeType3 { - return 5; - } - } - } -} - -/** @public */ -export enum SomeEnum { - A = 'A', - B = 'B', - C = 'C' -} - -/** @public */ -export function someFunction5(): SomeEnum.A { - return SomeEnum.A; -} - -/** @public */ -export class SomeClass { - public static staticProp = 5; -} - -/** @public */ -export function someFunction6(): typeof SomeClass.staticProp { - return 5; -} diff --git a/build-tests/api-extractor-scenarios/src/referenceTokens/index.ts b/build-tests/api-extractor-scenarios/src/referenceTokens/index.ts new file mode 100644 index 00000000000..cd7e15d6750 --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/referenceTokens/index.ts @@ -0,0 +1,88 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. +// See LICENSE in the project root for license information. + +import { Lib2Class } from 'api-extractor-lib2-test'; + +/** + * Various namespace scenarios. + * @public + */ +export namespace n1 { + type SomeType1 = number; + export function someFunction1(): SomeType1 { + return 5; + } + + export namespace n2 { + type SomeType2 = number; + export function someFunction2(): SomeType2 { + return 5; + } + + export namespace n3 { + export type SomeType3 = number; + export function someFunction3(): n2.n3.SomeType3 { + return 5; + } + } + + namespace n4 { + export type SomeType4 = number; + export function someFunction4(): n4.SomeType4 { + return 5; + } + } + } +} + +/** @public */ +export enum SomeEnum { + A = 'A', + B = 'B', + C = 'C' +} + +/** + * Enum member reference. + * @public + */ +export function someFunction5(): SomeEnum.A { + return SomeEnum.A; +} + +/** @public */ +export class SomeClass1 { + public static staticProp = 5; +} + +/** + * Static class member reference. + * @public + */ +export function someFunction6(): typeof SomeClass1.staticProp { + return 5; +} + +class SomeClass2 {} + +/** + * Unexported symbol reference. + * @public + */ +export class SomeClass3 extends SomeClass2 {} + +/** + * Global symbol reference. + * @public + */ +export function someFunction7(): Promise { + return Promise.resolve(); +} + +/** + * External symbol reference. + * @public + */ +export function someFunction8(): Lib2Class { + return new Lib2Class(); +} diff --git a/build-tests/api-extractor-scenarios/src/typeOf3/index.ts b/build-tests/api-extractor-scenarios/src/typeOf3/index.ts index 5819fffecae..85b73abb474 100644 --- a/build-tests/api-extractor-scenarios/src/typeOf3/index.ts +++ b/build-tests/api-extractor-scenarios/src/typeOf3/index.ts @@ -10,7 +10,7 @@ export function f1(x: number): typeof x { } /** - * A function that indirectly references its own parameter type. + * A function that indirectly references its own parameter type. * @public */ export function f2(x: number): keyof typeof x { @@ -18,7 +18,7 @@ export function f2(x: number): keyof typeof x { } /** - * A function that references its own type. + * A function that references its own type. * @public */ export function f3(): typeof f3 | undefined { diff --git a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml index 32016a04725..ec8e3e5c4fc 100644 --- a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml +++ b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml @@ -5,13 +5,13 @@ importers: typescript-newest-test: specifiers: '@rushstack/eslint-config': file:rushstack-eslint-config-2.6.2.tgz - '@rushstack/heft': file:rushstack-heft-0.46.5.tgz + '@rushstack/heft': file:rushstack-heft-0.46.6.tgz eslint: ~8.7.0 tslint: ~5.20.1 typescript: ~4.6.3 devDependencies: '@rushstack/eslint-config': file:../temp/tarballs/rushstack-eslint-config-2.6.2.tgz_eslint@8.7.0+typescript@4.6.4 - '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.46.5.tgz + '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.46.6.tgz eslint: 8.7.0 tslint: 5.20.1_typescript@4.6.4 typescript: 4.6.4 @@ -19,13 +19,13 @@ importers: typescript-v3-test: specifiers: '@rushstack/eslint-config': file:rushstack-eslint-config-2.6.2.tgz - '@rushstack/heft': file:rushstack-heft-0.46.5.tgz + '@rushstack/heft': file:rushstack-heft-0.46.6.tgz eslint: ~8.7.0 tslint: ~5.20.1 typescript: ~4.6.3 devDependencies: '@rushstack/eslint-config': file:../temp/tarballs/rushstack-eslint-config-2.6.2.tgz_eslint@8.7.0+typescript@4.6.4 - '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.46.5.tgz + '@rushstack/heft': file:../temp/tarballs/rushstack-heft-0.46.6.tgz eslint: 8.7.0 tslint: 5.20.1_typescript@4.6.4 typescript: 4.6.4 @@ -1804,10 +1804,10 @@ packages: - typescript dev: true - file:../temp/tarballs/rushstack-heft-0.46.5.tgz: - resolution: {tarball: file:../temp/tarballs/rushstack-heft-0.46.5.tgz} + file:../temp/tarballs/rushstack-heft-0.46.6.tgz: + resolution: {tarball: file:../temp/tarballs/rushstack-heft-0.46.6.tgz} name: '@rushstack/heft' - version: 0.46.5 + version: 0.46.6 engines: {node: '>=10.13.0'} hasBin: true dependencies: From 085e11ba843ec0531a251b8bb169e63796a47315 Mon Sep 17 00:00:00 2001 From: Zack Elliott Date: Tue, 2 Aug 2022 08:07:38 -0700 Subject: [PATCH 3/6] Ran rush change --- .../namespace-references_2022-08-02-15-07.json | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 common/changes/@microsoft/api-extractor/namespace-references_2022-08-02-15-07.json diff --git a/common/changes/@microsoft/api-extractor/namespace-references_2022-08-02-15-07.json b/common/changes/@microsoft/api-extractor/namespace-references_2022-08-02-15-07.json new file mode 100644 index 00000000000..d5805a01014 --- /dev/null +++ b/common/changes/@microsoft/api-extractor/namespace-references_2022-08-02-15-07.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "packageName": "@microsoft/api-extractor", + "comment": "Fix incorrect declaration references for local symbols within namespaces", + "type": "patch" + } + ], + "packageName": "@microsoft/api-extractor" +} \ No newline at end of file From 4dd03470a4e1f24c9c9dd264e73cd9714a63e68f Mon Sep 17 00:00:00 2001 From: Zack Elliott Date: Tue, 2 Aug 2022 08:10:28 -0700 Subject: [PATCH 4/6] Cleanup comments a bit --- .../src/generators/DeclarationReferenceGenerator.ts | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts b/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts index 0855dfba7c5..11fc3777df7 100644 --- a/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts +++ b/apps/api-extractor/src/generators/DeclarationReferenceGenerator.ts @@ -324,13 +324,11 @@ export class DeclarationReferenceGenerator { } } - // At this point, we either have... + // At this point, we have a local symbol in a module. const sourceFile: ts.SourceFile | undefined = declaration?.getSourceFile(); if (sourceFile && ts.isExternalModule(sourceFile)) { - // ...a local symbol in some source file module. return new DeclarationReference(this._sourceFileToModuleSource(sourceFile)); } else { - // ...a global symbol. return new DeclarationReference(GlobalSource.instance); } } From 4deb6f6f4d67ce09b502ee0ebf8cd12c1e7fb6a5 Mon Sep 17 00:00:00 2001 From: Zack Elliott Date: Tue, 2 Aug 2022 08:34:55 -0700 Subject: [PATCH 5/6] Removed unnecessary test scenario --- .../api-extractor-scenarios.api.json | 28 ------------------- .../api-extractor-scenarios.api.md | 3 -- .../etc/mergedDeclarations/rollup.d.ts | 3 -- .../src/mergedDeclarations/index.ts | 5 ---- 4 files changed, 39 deletions(-) diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json index f8400c5577a..f79add87f66 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.json @@ -434,34 +434,6 @@ } ], "extendsTokenRanges": [] - }, - { - "kind": "Function", - "canonicalReference": "api-extractor-scenarios!someFunction:function(1)", - "docComment": "/**\n * @public\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "export declare function someFunction(): " - }, - { - "kind": "Reference", - "text": "MergedClassAndInterface", - "canonicalReference": "api-extractor-scenarios!MergedClassAndInterface:class" - }, - { - "kind": "Content", - "text": ";" - } - ], - "returnTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - }, - "releaseTag": "Public", - "overloadIndex": 1, - "parameters": [], - "name": "someFunction" } ] } diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md index fa16cea4f17..86cdc9e8e33 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/api-extractor-scenarios.api.md @@ -42,9 +42,6 @@ export interface MergedInterfaces { someProp: number; } -// @public (undocumented) -export function someFunction(): MergedClassAndInterface; - // (No @packageDocumentation comment for this package) ``` diff --git a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts index d557a24d0d1..426076798ca 100644 --- a/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/mergedDeclarations/rollup.d.ts @@ -29,7 +29,4 @@ export declare interface MergedInterfaces { someProp: number; } -/** @public */ -export declare function someFunction(): MergedClassAndInterface; - export { } diff --git a/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts b/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts index 77d19957df3..40ac8801c21 100644 --- a/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts +++ b/build-tests/api-extractor-scenarios/src/mergedDeclarations/index.ts @@ -32,8 +32,3 @@ export class MergedClassAndNamespace { export namespace MergedClassAndNamespace { export let anotherProp: number; } - -/** @public */ -export function someFunction(): MergedClassAndInterface { - return new MergedClassAndInterface(); -} From 3f978c238fed527980fe7bdd40c08f257f36f636 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Wed, 10 Aug 2022 01:07:15 -0700 Subject: [PATCH 6/6] rush build --- .../api-extractor-scenarios.api.json | 248 +++++++++--------- .../api-extractor-scenarios.api.md | 44 ++-- .../etc/apiItemKinds/rollup.d.ts | 39 +-- .../workspace/common/pnpm-lock.yaml | 6 +- 4 files changed, 175 insertions(+), 162 deletions(-) diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json index ea2a8cca541..5b822e4801b 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.json @@ -219,109 +219,6 @@ ], "implementsTokenRanges": [] }, - { - "kind": "Class", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals:class", - "docComment": "/**\n * @public\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "export declare class ClassWithTypeLiterals " - } - ], - "releaseTag": "Public", - "name": "ClassWithTypeLiterals", - "preserveMemberOrder": false, - "members": [ - { - "kind": "Method", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals#method1:member(1)", - "docComment": "/**\n * type literal in\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "method1(vector: " - }, - { - "kind": "Content", - "text": "{\n x: number;\n y: number;\n }" - }, - { - "kind": "Content", - "text": "): " - }, - { - "kind": "Content", - "text": "void" - }, - { - "kind": "Content", - "text": ";" - } - ], - "isStatic": false, - "returnTypeTokenRange": { - "startIndex": 3, - "endIndex": 4 - }, - "releaseTag": "Public", - "isProtected": false, - "overloadIndex": 1, - "parameters": [ - { - "parameterName": "vector", - "parameterTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - }, - "isOptional": false - } - ], - "isOptional": false, - "name": "method1" - }, - { - "kind": "Method", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals#method2:member(1)", - "docComment": "/**\n * type literal output\n */\n", - "excerptTokens": [ - { - "kind": "Content", - "text": "method2(): " - }, - { - "kind": "Content", - "text": "{\n classValue: " - }, - { - "kind": "Reference", - "text": "ClassWithTypeLiterals", - "canonicalReference": "api-extractor-scenarios!ClassWithTypeLiterals:class" - }, - { - "kind": "Content", - "text": ";\n callback: () => number;\n } | undefined" - }, - { - "kind": "Content", - "text": ";" - } - ], - "isStatic": false, - "returnTypeTokenRange": { - "startIndex": 1, - "endIndex": 4 - }, - "releaseTag": "Public", - "isProtected": false, - "overloadIndex": 1, - "parameters": [], - "isOptional": false, - "name": "method2" - } - ], - "implementsTokenRanges": [] - }, { "kind": "Class", "canonicalReference": "api-extractor-scenarios!ClassWithTypeParameter:class", @@ -540,61 +437,110 @@ }, { "kind": "Namespace", - "canonicalReference": "api-extractor-scenarios!NamespaceContainingVariable:namespace", + "canonicalReference": "api-extractor-scenarios!n1:namespace", "docComment": "/**\n * @public\n */\n", "excerptTokens": [ { "kind": "Content", - "text": "export declare namespace NamespaceContainingVariable " + "text": "export declare namespace n1 " } ], "releaseTag": "Public", - "name": "NamespaceContainingVariable", + "name": "n1", "preserveMemberOrder": false, "members": [ { - "kind": "Variable", - "canonicalReference": "api-extractor-scenarios!NamespaceContainingVariable.constVariable:var", + "kind": "Namespace", + "canonicalReference": "api-extractor-scenarios!n1.n2:namespace", "docComment": "", "excerptTokens": [ { "kind": "Content", - "text": "constVariable: " - }, + "text": "export namespace n2 " + } + ], + "releaseTag": "Public", + "name": "n2", + "preserveMemberOrder": false, + "members": [ + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.n2.SomeClass3:class", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "class SomeClass3 " + } + ], + "releaseTag": "Public", + "name": "SomeClass3", + "preserveMemberOrder": false, + "members": [], + "implementsTokenRanges": [] + } + ] + }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.SomeClass1:class", + "docComment": "", + "excerptTokens": [ { "kind": "Content", - "text": "object[]" + "text": "class SomeClass1 " } ], - "isReadonly": false, "releaseTag": "Public", - "name": "constVariable", - "variableTypeTokenRange": { - "startIndex": 1, - "endIndex": 2 - } + "name": "SomeClass1", + "preserveMemberOrder": false, + "members": [], + "implementsTokenRanges": [] }, { - "kind": "Variable", - "canonicalReference": "api-extractor-scenarios!NamespaceContainingVariable.variable:var", + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.SomeClass2:class", "docComment": "", "excerptTokens": [ { "kind": "Content", - "text": "variable: " + "text": "export class SomeClass2 extends " + }, + { + "kind": "Reference", + "text": "SomeClass1", + "canonicalReference": "api-extractor-scenarios!n1~SomeClass1:class" }, { "kind": "Content", - "text": "object[]" + "text": " " } ], - "isReadonly": false, "releaseTag": "Public", - "name": "variable", - "variableTypeTokenRange": { + "name": "SomeClass2", + "preserveMemberOrder": false, + "members": [], + "extendsTokenRange": { "startIndex": 1, "endIndex": 2 - } + }, + "implementsTokenRanges": [] + }, + { + "kind": "Class", + "canonicalReference": "api-extractor-scenarios!n1.SomeClass4:class", + "docComment": "", + "excerptTokens": [ + { + "kind": "Content", + "text": "class SomeClass4 " + } + ], + "releaseTag": "Public", + "name": "SomeClass4", + "preserveMemberOrder": false, + "members": [], + "implementsTokenRanges": [] } ] }, @@ -913,6 +859,58 @@ ], "implementsTokenRanges": [] }, + { + "kind": "Function", + "canonicalReference": "api-extractor-scenarios!someFunction:function(1)", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare function someFunction(): " + }, + { + "kind": "Content", + "text": "void" + }, + { + "kind": "Content", + "text": ";" + } + ], + "returnTypeTokenRange": { + "startIndex": 1, + "endIndex": 2 + }, + "releaseTag": "Public", + "overloadIndex": 1, + "parameters": [], + "name": "someFunction" + }, + { + "kind": "TypeAlias", + "canonicalReference": "api-extractor-scenarios!SomeType:type", + "docComment": "/**\n * @public\n */\n", + "excerptTokens": [ + { + "kind": "Content", + "text": "export declare type SomeType = " + }, + { + "kind": "Content", + "text": "number" + }, + { + "kind": "Content", + "text": ";" + } + ], + "releaseTag": "Public", + "name": "SomeType", + "typeTokenRange": { + "startIndex": 1, + "endIndex": 2 + } + }, { "kind": "Variable", "canonicalReference": "api-extractor-scenarios!VARIABLE_WITHOUT_EXPLICIT_TYPE:var", diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md index b068955b6a8..c0743f1c37e 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/api-extractor-scenarios.api.md @@ -10,18 +10,6 @@ export abstract class AbstractClass { abstract member(): void; } -// @public (undocumented) -export class ClassWithTypeLiterals { - method1(vector: { - x: number; - y: number; - }): void; - method2(): { - classValue: ClassWithTypeLiterals; - callback: () => number; - } | undefined; -} - // @public (undocumented) export class ClassWithTypeParameter { } @@ -50,11 +38,27 @@ export interface IInterface { } // @public (undocumented) -export namespace NamespaceContainingVariable { - let // (undocumented) - variable: object[]; - let // (undocumented) - constVariable: object[]; +export namespace n1 { + // (undocumented) + export namespace n2 { + // (undocumented) + export class SomeClass3 { + } + } + // (undocumented) + export class SomeClass1 { + } + // (undocumented) + export class SomeClass2 extends SomeClass1 { + } + {}; +} + +// @public (undocumented) +export namespace n1 { + // (undocumented) + export class SomeClass4 { + } } // @public (undocumented) @@ -84,6 +88,12 @@ export class SimpleClass { set writeableProperty(value: string); } +// @public (undocumented) +export function someFunction(): void; + +// @public (undocumented) +export type SomeType = number; + // @public (undocumented) export const VARIABLE_WITHOUT_EXPLICIT_TYPE = "hello"; diff --git a/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts index a40d02957ef..dbe1c3219c1 100644 --- a/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts +++ b/build-tests/api-extractor-scenarios/etc/apiItemKinds/rollup.d.ts @@ -3,20 +3,6 @@ export declare abstract class AbstractClass { abstract member(): void; } -/** @public */ -export declare class ClassWithTypeLiterals { - /** type literal in */ - method1(vector: { - x: number; - y: number; - }): void; - /** type literal output */ - method2(): { - classValue: ClassWithTypeLiterals; - callback: () => number; - } | undefined; -} - /** @public */ export declare class ClassWithTypeParameter { } @@ -41,9 +27,22 @@ export declare interface IInterface { } /** @public */ -export declare namespace NamespaceContainingVariable { - let variable: object[]; - let constVariable: object[]; +export declare namespace n1 { + export class SomeClass1 { + } + export class SomeClass2 extends SomeClass1 { + } + export namespace n2 { + export class SomeClass3 { + } + } + {}; +} + +/** @public */ +export declare namespace n1 { + export class SomeClass4 { + } } /** @public */ @@ -76,6 +75,12 @@ export declare class SimpleClass { readonly someReadonlyPropWithType: number; } +/** @public */ +export declare function someFunction(): void; + +/** @public */ +export declare type SomeType = number; + /** @public */ export declare const VARIABLE_WITHOUT_EXPLICIT_TYPE = "hello"; diff --git a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml index 6c0cff58037..0edc8cb3e66 100644 --- a/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml +++ b/build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml @@ -995,7 +995,7 @@ packages: dev: true /inherits/2.0.4: - resolution: {integrity: sha1-D6LGT5MpF8NDOg3tVTY6rjdBa3w=} + resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==} dev: true /internal-slot/1.0.3: @@ -1217,7 +1217,7 @@ packages: dev: true /minimatch/3.1.2: - resolution: {integrity: sha1-Gc0ZS/0+Qo8EmnCBfAONiatL41s=} + resolution: {integrity: sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==} dependencies: brace-expansion: 1.1.11 dev: true @@ -1340,7 +1340,7 @@ packages: dev: true /path-parse/1.0.7: - resolution: {integrity: sha1-+8EUtgykKzDZ2vWFjkvWi77bZzU=} + resolution: {integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==} dev: true /path-type/4.0.0: