From 86674a281ec80fd86cd368f67a9a3cdeabeaab1e Mon Sep 17 00:00:00 2001 From: Ron Buckton Date: Sat, 7 Sep 2019 15:16:53 -0700 Subject: [PATCH] Remove yaml references for type params and toJSON/fromJSON from ExcerptToken --- .../src/documenters/YamlDocumenter.ts | 136 ++++++++---------- .../api-documenter-test/idocinterface6.yml | 1 - common/reviews/api/api-extractor-model.api.md | 6 +- 3 files changed, 58 insertions(+), 85 deletions(-) diff --git a/apps/api-documenter/src/documenters/YamlDocumenter.ts b/apps/api-documenter/src/documenters/YamlDocumenter.ts index c52f732314a..0826198fa1b 100644 --- a/apps/api-documenter/src/documenters/YamlDocumenter.ts +++ b/apps/api-documenter/src/documenters/YamlDocumenter.ts @@ -63,6 +63,7 @@ const yamlApiSchema: JsonSchema = JsonSchema.fromFile(path.join(__dirname, '..', interface IYamlReferences { references: IYamlReference[]; typeNameToUid: Map; + uidTypeReferenceCounters: Map; } /** @@ -73,9 +74,7 @@ export class YamlDocumenter { private readonly _markdownEmitter: CustomMarkdownEmitter; private _apiItemsByCanonicalReference: Map; - private _knownTypeParameters: Set | undefined; private _yamlReferences: IYamlReferences | undefined; - private _uidTypeReferenceCounters: Map; private _outputFolder: string; @@ -83,7 +82,6 @@ export class YamlDocumenter { this._apiModel = apiModel; this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel); this._apiItemsByCanonicalReference = new Map(); - this._uidTypeReferenceCounters = new Map(); this._initApiItems(); } @@ -118,94 +116,78 @@ export class YamlDocumenter { } private _visitApiItems(apiItem: ApiDocumentedItem, parentYamlFile: IYamlApiFile | undefined): boolean { - const savedKnownTypeParameters: Set | undefined = this._knownTypeParameters; - try { - // Track type parameters declared by a declaration so that we do not resolve them - // when looking up types in _linkToUidIfPossible() - if (ApiTypeParameterListMixin.isBaseClassOf(apiItem)) { - this._knownTypeParameters = savedKnownTypeParameters - ? new Set(savedKnownTypeParameters) - : new Set(); - for (const typeParameter of apiItem.typeParameters) { - this._knownTypeParameters.add(typeParameter.name); - } - } + const yamlItem: IYamlItem | undefined = this._generateYamlItem(apiItem); + if (!yamlItem) { + return false; + } - const yamlItem: IYamlItem | undefined = this._generateYamlItem(apiItem); - if (!yamlItem) { - return false; - } + this.onCustomizeYamlItem(yamlItem); - this.onCustomizeYamlItem(yamlItem); + if (this._shouldEmbed(apiItem.kind)) { + if (!parentYamlFile) { + throw new InternalError('Missing file context'); + } + parentYamlFile.items.push(yamlItem); + } else { + const newYamlFile: IYamlApiFile = { + items: [] + }; + newYamlFile.items.push(yamlItem); - if (this._shouldEmbed(apiItem.kind)) { - if (!parentYamlFile) { - throw new InternalError('Missing file context'); - } - parentYamlFile.items.push(yamlItem); + let children: ReadonlyArray; + if (apiItem.kind === ApiItemKind.Package) { + // Skip over the entry point, since it's not part of the documentation hierarchy + children = apiItem.members[0].members; } else { - const newYamlFile: IYamlApiFile = { - items: [] - }; - newYamlFile.items.push(yamlItem); - - let children: ReadonlyArray; - if (apiItem.kind === ApiItemKind.Package) { - // Skip over the entry point, since it's not part of the documentation hierarchy - children = apiItem.members[0].members; - } else { - children = apiItem.members; - } + children = apiItem.members; + } - const flattenedChildren: ApiItem[] = this._flattenNamespaces(children); + const flattenedChildren: ApiItem[] = this._flattenNamespaces(children); - for (const child of flattenedChildren) { - if (child instanceof ApiDocumentedItem) { - if (this._visitApiItems(child, newYamlFile)) { - if (!yamlItem.children) { - yamlItem.children = []; - } - yamlItem.children.push(this._getUid(child)); + for (const child of flattenedChildren) { + if (child instanceof ApiDocumentedItem) { + if (this._visitApiItems(child, newYamlFile)) { + if (!yamlItem.children) { + yamlItem.children = []; } + yamlItem.children.push(this._getUid(child)); } } + } - if (this._yamlReferences) { - if (this._yamlReferences.references.length > 0) { - if (newYamlFile.references) { - newYamlFile.references = [...newYamlFile.references, ...this._yamlReferences.references]; - } else { - newYamlFile.references = this._yamlReferences.references; - } + if (this._yamlReferences) { + if (this._yamlReferences.references.length > 0) { + if (newYamlFile.references) { + newYamlFile.references = [...newYamlFile.references, ...this._yamlReferences.references]; + } else { + newYamlFile.references = this._yamlReferences.references; } - this._yamlReferences = undefined; } + this._yamlReferences = undefined; + } - const yamlFilePath: string = this._getYamlFilePath(apiItem); + const yamlFilePath: string = this._getYamlFilePath(apiItem); - if (apiItem.kind === ApiItemKind.Package) { - console.log('Writing ' + yamlFilePath); - } + if (apiItem.kind === ApiItemKind.Package) { + console.log('Writing ' + yamlFilePath); + } - this._writeYamlFile(newYamlFile, yamlFilePath, 'UniversalReference', yamlApiSchema); + this._writeYamlFile(newYamlFile, yamlFilePath, 'UniversalReference', yamlApiSchema); - if (parentYamlFile) { - if (!parentYamlFile.references) { - parentYamlFile.references = []; - } + if (parentYamlFile) { + if (!parentYamlFile.references) { + parentYamlFile.references = []; + } - parentYamlFile.references.push({ - uid: this._getUid(apiItem), - name: this._getYamlItemName(apiItem) - }); + parentYamlFile.references.push({ + uid: this._getUid(apiItem), + name: this._getYamlItemName(apiItem) + }); - } } - - return true; - } finally { - this._knownTypeParameters = savedKnownTypeParameters; } + + return true; } // Since the YAML schema does not yet support nested namespaces, we simply omit them from @@ -636,7 +618,8 @@ export class YamlDocumenter { if (!this._yamlReferences) { this._yamlReferences = { references: [], - typeNameToUid: new Map() + typeNameToUid: new Map(), + uidTypeReferenceCounters: new Map() }; } return this._yamlReferences; @@ -662,11 +645,6 @@ export class YamlDocumenter { const typeName: string = typeExcerpt.text.trim(); - // Record a reference to a type parameter as its name, so as not to resolve to a conflicting name - if (this._knownTypeParameters && this._knownTypeParameters.has(typeName)) { - return this._recordYamlReference(this._ensureYamlReferences(), typeName, typeName); - } - // If there are no references to be used for a complex type, return the type name. if (!excerptTokens.some(tok => tok.kind === ExcerptTokenKind.Reference && !!tok.canonicalReference)) { return typeName; @@ -700,8 +678,8 @@ export class YamlDocumenter { // Keep track of the count for the base uid (without meaning or overload index) to ensure // that each complex type reference is unique. - const counter: number = this._uidTypeReferenceCounters.get(baseUid) || 0; - this._uidTypeReferenceCounters.set(baseUid, counter + 1); + const counter: number = yamlReferences.uidTypeReferenceCounters.get(baseUid) || 0; + yamlReferences.uidTypeReferenceCounters.set(baseUid, counter + 1); const uid: string = contextUid .addNavigationStep(Navigation.Locals, `${counter}`) diff --git a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/idocinterface6.yml b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/idocinterface6.yml index 8b84d736d5a..c52c45fcee5 100644 --- a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/idocinterface6.yml +++ b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/idocinterface6.yml @@ -112,7 +112,6 @@ references: fullName: IDocInterface1 - name: '[]' fullName: '[]' - - uid: T - uid: 'api-documenter-test!IDocInterface6#intersectionProperty~0:complex' name: IDocInterface1 & IDocInterface2 fullName: IDocInterface1 & IDocInterface2 diff --git a/common/reviews/api/api-extractor-model.api.md b/common/reviews/api/api-extractor-model.api.md index 8e30a99730a..2e4ac027605 100644 --- a/common/reviews/api/api-extractor-model.api.md +++ b/common/reviews/api/api-extractor-model.api.md @@ -617,14 +617,10 @@ export class ExcerptToken { // (undocumented) readonly canonicalReference: DeclarationReference | undefined; // (undocumented) - static fromJSON(object: IExcerptToken): ExcerptToken; - // (undocumented) readonly kind: ExcerptTokenKind; // (undocumented) readonly text: string; - // (undocumented) - toJSON(): IExcerptToken; -} + } // @public (undocumented) export const enum ExcerptTokenKind {