Skip to content

Commit 4d12579

Browse files
pgonzalpgonzal
committed
Update api-documenter
1 parent c0dee76 commit 4d12579

File tree

3 files changed

+36
-34
lines changed

3 files changed

+36
-34
lines changed

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

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,10 @@ import {
3636
ApiDeclarationMixin,
3737
ApiStaticMixin,
3838
ApiPropertyItem,
39-
ApiFunctionLikeMixin,
4039
ApiInterface,
4140
Excerpt,
42-
ApiMethodItem
41+
ApiParameterListMixin,
42+
ApiReturnTypeMixin
4343
} from '@microsoft/api-extractor';
4444

4545
import { CustomDocNodes } from '../nodes/CustomDocNodeKind';
@@ -106,7 +106,7 @@ export class MarkdownDocumenter {
106106
output.appendNode(new DocHeading({ configuration, title: `${scopedName} namespace` }));
107107
break;
108108
case ApiItemKind.Package:
109-
const unscopedPackageName: string = PackageName.getUnscopedName(apiItem.name);
109+
const unscopedPackageName: string = PackageName.getUnscopedName(apiItem.displayName);
110110
output.appendNode(new DocHeading({ configuration, title: `${unscopedPackageName} package` }));
111111
break;
112112
case ApiItemKind.Property:
@@ -175,7 +175,7 @@ export class MarkdownDocumenter {
175175
break;
176176
case ApiItemKind.Method:
177177
case ApiItemKind.MethodSignature:
178-
this._writeFunctionLikeTables(output, apiItem as ApiFunctionLikeMixin);
178+
this._writeParameterTables(output, apiItem as ApiParameterListMixin);
179179
break;
180180
case ApiItemKind.Namespace:
181181
break;
@@ -515,14 +515,14 @@ export class MarkdownDocumenter {
515515
/**
516516
* GENERATE PAGE: FUNCTION-LIKE
517517
*/
518-
private _writeFunctionLikeTables(output: DocSection, apiFunctionLike: ApiFunctionLikeMixin): void {
518+
private _writeParameterTables(output: DocSection, apiParameterListMixin: ApiParameterListMixin): void {
519519
const configuration: TSDocConfiguration = this._tsdocConfiguration;
520520

521521
const parametersTable: DocTable = new DocTable({ configuration,
522522
headerTitles: [ 'Parameter', 'Type', 'Description' ]
523523
});
524524

525-
for (const apiParameter of apiFunctionLike.parameters) {
525+
for (const apiParameter of apiParameterListMixin.parameters) {
526526
const parameterDescription: DocSection = new DocSection({ configuration } );
527527
if (apiParameter.tsdocParamBlock) {
528528
this._appendSection(parameterDescription, apiParameter.tsdocParamBlock.content);
@@ -550,8 +550,8 @@ export class MarkdownDocumenter {
550550
output.appendNode(parametersTable);
551551
}
552552

553-
if (apiFunctionLike instanceof ApiMethodItem) {
554-
const returnTypeExcerpt: Excerpt = apiFunctionLike.returnTypeExcerpt;
553+
if (ApiReturnTypeMixin.isBaseClassOf(apiParameterListMixin)) {
554+
const returnTypeExcerpt: Excerpt = apiParameterListMixin.returnTypeExcerpt;
555555
output.appendNode(
556556
new DocParagraph({ configuration }, [
557557
new DocEmphasisSpan({ configuration, bold: true}, [
@@ -566,9 +566,9 @@ export class MarkdownDocumenter {
566566
])
567567
);
568568

569-
if (apiFunctionLike instanceof ApiDocumentedItem) {
570-
if (apiFunctionLike.tsdocComment && apiFunctionLike.tsdocComment.returnsBlock) {
571-
this._appendSection(output, apiFunctionLike.tsdocComment.returnsBlock.content);
569+
if (apiParameterListMixin instanceof ApiDocumentedItem) {
570+
if (apiParameterListMixin.tsdocComment && apiParameterListMixin.tsdocComment.returnsBlock) {
571+
this._appendSection(output, apiParameterListMixin.tsdocComment.returnsBlock.content);
572572
}
573573
}
574574
}
@@ -672,7 +672,7 @@ export class MarkdownDocumenter {
672672
new DocLinkTag({
673673
configuration: this._tsdocConfiguration,
674674
tagName: '@link',
675-
linkText: hierarchyItem.name,
675+
linkText: hierarchyItem.displayName,
676676
urlDestination: this._getLinkFilenameForApiItem(hierarchyItem)
677677
})
678678
]);
@@ -719,8 +719,8 @@ export class MarkdownDocumenter {
719719
let baseName: string = '';
720720
for (const hierarchyItem of apiItem.getHierarchy()) {
721721
// For overloaded methods, add a suffix such as "MyClass.myMethod_2".
722-
let qualifiedName: string = hierarchyItem.name;
723-
if (ApiFunctionLikeMixin.isBaseClassOf(hierarchyItem)) {
722+
let qualifiedName: string = hierarchyItem.displayName;
723+
if (ApiParameterListMixin.isBaseClassOf(hierarchyItem)) {
724724
if (hierarchyItem.overloadIndex > 0) {
725725
qualifiedName += `_${hierarchyItem.overloadIndex}`;
726726
}
@@ -731,7 +731,7 @@ export class MarkdownDocumenter {
731731
case ApiItemKind.EntryPoint:
732732
break;
733733
case ApiItemKind.Package:
734-
baseName = PackageName.getUnscopedName(hierarchyItem.name);
734+
baseName = PackageName.getUnscopedName(hierarchyItem.displayName);
735735
break;
736736
default:
737737
baseName += '.' + qualifiedName;

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

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,12 @@ import {
2323
ApiPropertyItem,
2424
ApiItemContainerMixin,
2525
ApiPackage,
26-
ApiFunctionLikeMixin,
2726
ApiEnumMember,
28-
ApiMethodItem,
2927
ApiClass,
30-
ApiInterface
28+
ApiInterface,
29+
ApiParameterListMixin,
30+
ApiMethod,
31+
ApiMethodSignature
3132
} from '@microsoft/api-extractor';
3233

3334
import {
@@ -202,7 +203,7 @@ export class YamlDocumenter {
202203
if (apiItem.kind === ApiItemKind.Namespace) {
203204
// Namespaces don't have nodes yet
204205
tocItem = {
205-
name: apiItem.name
206+
name: apiItem.displayName
206207
};
207208
} else {
208209
if (this._shouldEmbed(apiItem.kind)) {
@@ -212,12 +213,12 @@ export class YamlDocumenter {
212213

213214
if (apiItem.kind === ApiItemKind.Package) {
214215
tocItem = {
215-
name: PackageName.getUnscopedName(apiItem.name),
216+
name: PackageName.getUnscopedName(apiItem.displayName),
216217
uid: this._getUid(apiItem)
217218
};
218219
} else {
219220
tocItem = {
220-
name: apiItem.name,
221+
name: apiItem.displayName,
221222
uid: this._getUid(apiItem)
222223
};
223224
}
@@ -315,7 +316,7 @@ export class YamlDocumenter {
315316
case ApiItemKind.Method:
316317
case ApiItemKind.MethodSignature:
317318
yamlItem.type = 'method';
318-
this._populateYamlFunctionLike(yamlItem, apiItem as ApiMethodItem);
319+
this._populateYamlFunctionLike(yamlItem, apiItem as ApiMethod | ApiMethodSignature);
319320
break;
320321
/*
321322
case ApiItemKind.Constructor:
@@ -349,7 +350,7 @@ export class YamlDocumenter {
349350
if (apiItem.kind !== ApiItemKind.Package && !this._shouldEmbed(apiItem.kind)) {
350351
const associatedPackage: ApiPackage | undefined = apiItem.getAssociatedPackage();
351352
if (!associatedPackage) {
352-
throw new Error('Unable to determine associated package for ' + apiItem.name);
353+
throw new Error('Unable to determine associated package for ' + apiItem.displayName);
353354
}
354355
yamlItem.package = this._getUid(associatedPackage);
355356
}
@@ -394,7 +395,7 @@ export class YamlDocumenter {
394395
}
395396
}
396397

397-
private _populateYamlFunctionLike(yamlItem: Partial<IYamlItem>, apiItem: ApiMethodItem): void {
398+
private _populateYamlFunctionLike(yamlItem: Partial<IYamlItem>, apiItem: ApiMethod | ApiMethodSignature): void {
398399
const syntax: IYamlSyntax = {
399400
content: apiItem.getExcerptWithModifiers()
400401
};
@@ -498,8 +499,8 @@ export class YamlDocumenter {
498499
for (const hierarchyItem of apiItem.getHierarchy()) {
499500

500501
// For overloaded methods, add a suffix such as "MyClass.myMethod_2".
501-
let qualifiedName: string = hierarchyItem.name;
502-
if (ApiFunctionLikeMixin.isBaseClassOf(hierarchyItem)) {
502+
let qualifiedName: string = hierarchyItem.displayName;
503+
if (ApiParameterListMixin.isBaseClassOf(hierarchyItem)) {
503504
if (hierarchyItem.overloadIndex > 0) {
504505
qualifiedName += `_${hierarchyItem.overloadIndex}`;
505506
}
@@ -510,7 +511,7 @@ export class YamlDocumenter {
510511
case ApiItemKind.EntryPoint:
511512
break;
512513
case ApiItemKind.Package:
513-
result += PackageName.getUnscopedName(hierarchyItem.name);
514+
result += PackageName.getUnscopedName(hierarchyItem.displayName);
514515
break;
515516
default:
516517
result += '.';
@@ -545,7 +546,7 @@ export class YamlDocumenter {
545546
case ApiItemKind.Enum:
546547
case ApiItemKind.Interface:
547548
// Attempt to register both the fully qualified name and the short name
548-
const namesForType: string[] = [apiItem.name];
549+
const namesForType: string[] = [apiItem.displayName];
549550

550551
// Note that nameWithDot cannot conflict with apiItem.name (because apiItem.name
551552
// cannot contain a dot)
@@ -631,15 +632,15 @@ export class YamlDocumenter {
631632
case ApiItemKind.EntryPoint:
632633
break;
633634
case ApiItemKind.Package:
634-
result += PackageName.getUnscopedName(current.name);
635+
result += PackageName.getUnscopedName(current.displayName);
635636
break;
636637
default:
637638
if (current.parent && current.parent.kind === ApiItemKind.EntryPoint) {
638639
result += '/';
639640
} else {
640641
result += '.';
641642
}
642-
result += current.name;
643+
result += current.displayName;
643644
break;
644645
}
645646
}

‎apps/api-documenter/src/utils/Utilities.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,18 @@
22
// See LICENSE in the project root for license information.
33

44
import {
5-
ApiFunctionLikeMixin, ApiItem
5+
ApiParameterListMixin,
6+
ApiItem
67
} from '@microsoft/api-extractor';
78

89
export class Utilities {
910
/**
1011
* Generates a concise signature for a function. Example: "getArea(width, height)"
1112
*/
1213
public static getConciseSignature(apiItem: ApiItem): string {
13-
if (ApiFunctionLikeMixin.isBaseClassOf(apiItem)) {
14-
return apiItem.name + '(' + apiItem.parameters.map(x => x.name).join(', ') + ')';
14+
if (ApiParameterListMixin.isBaseClassOf(apiItem)) {
15+
return apiItem.displayName + '(' + apiItem.parameters.map(x => x.name).join(', ') + ')';
1516
}
16-
return apiItem.name;
17+
return apiItem.displayName;
1718
}
1819
}

0 commit comments

Comments
 (0)