Skip to content

Commit 3b18da1

Browse files
committed
add addFileNameSuffix option
1 parent c31ded6 commit 3b18da1

File tree

4 files changed

+95
-26
lines changed

4 files changed

+95
-26
lines changed

repo-scripts/api-documenter/src/cli/BaseAction.ts

+17-1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import colors from 'colors';
2424

2525
import {
2626
CommandLineAction,
27+
CommandLineFlagParameter,
2728
CommandLineStringParameter
2829
} from '@rushstack/ts-command-line';
2930
import { FileSystem } from '@rushstack/node-core-library';
@@ -39,11 +40,13 @@ export interface IBuildApiModelResult {
3940
apiModel: ApiModel;
4041
inputFolder: string;
4142
outputFolder: string;
43+
addFileNameSuffix: boolean;
4244
}
4345

4446
export abstract class BaseAction extends CommandLineAction {
4547
private _inputFolderParameter!: CommandLineStringParameter;
4648
private _outputFolderParameter!: CommandLineStringParameter;
49+
private _fileNameSuffixParameter!: CommandLineFlagParameter;
4750

4851
protected onDefineParameters(): void {
4952
// override
@@ -65,6 +68,17 @@ export abstract class BaseAction extends CommandLineAction {
6568
` ANY EXISTING CONTENTS WILL BE DELETED!` +
6669
` If omitted, the default is "./${this.actionName}"`
6770
});
71+
72+
this._fileNameSuffixParameter = this.defineFlagParameter({
73+
parameterLongName: '--name-suffix',
74+
parameterShortName: '-s',
75+
description:
76+
`Add suffix to interface and class names in the file path.` +
77+
`For example, packageA.myinterface_i.md for MyInterface interface, ` +
78+
`Add packageA.myclass_c.md for MyClass class.` +
79+
`This is to avoid name conflict in case packageA also has, for example, a namespace with the same name in lowercase.` +
80+
`This option is specifically designed for the Admin SDK where such case occurs.`
81+
});
6882
}
6983

7084
protected buildApiModel(): IBuildApiModelResult {
@@ -79,6 +93,8 @@ export abstract class BaseAction extends CommandLineAction {
7993
this._outputFolderParameter.value || `./${this.actionName}`;
8094
FileSystem.ensureFolder(outputFolder);
8195

96+
const addFileNameSuffix: boolean = this._fileNameSuffixParameter.value;
97+
8298
for (const filename of FileSystem.readFolder(inputFolder)) {
8399
if (filename.match(/\.api\.json$/i)) {
84100
console.log(`Reading ${filename}`);
@@ -89,7 +105,7 @@ export abstract class BaseAction extends CommandLineAction {
89105

90106
this._applyInheritDoc(apiModel, apiModel);
91107

92-
return { apiModel, inputFolder, outputFolder };
108+
return { apiModel, inputFolder, outputFolder, addFileNameSuffix };
93109
}
94110

95111
// TODO: This is a temporary workaround. The long term plan is for API Extractor's DocCommentEnhancer

repo-scripts/api-documenter/src/cli/MarkdownAction.ts

+3-2
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,13 @@ export class MarkdownAction extends BaseAction {
3535

3636
protected async onExecute(): Promise<void> {
3737
// override
38-
const { apiModel, outputFolder } = this.buildApiModel();
38+
const { apiModel, outputFolder, addFileNameSuffix } = this.buildApiModel();
3939

4040
const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({
4141
apiModel,
4242
documenterConfig: undefined,
43-
outputFolder
43+
outputFolder,
44+
addFileNameSuffix
4445
});
4546
markdownDocumenter.generateFiles();
4647
}

repo-scripts/api-documenter/src/documenters/MarkdownDocumenter.ts

+52-14
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ export interface IMarkdownDocumenterOptions {
9191
apiModel: ApiModel;
9292
documenterConfig: DocumenterConfig | undefined;
9393
outputFolder: string;
94+
addFileNameSuffix: boolean;
9495
}
9596

9697
/**
@@ -104,11 +105,13 @@ export class MarkdownDocumenter {
104105
private readonly _markdownEmitter: CustomMarkdownEmitter;
105106
private readonly _outputFolder: string;
106107
private readonly _pluginLoader: PluginLoader;
108+
private readonly _addFileNameSuffix: boolean;
107109

108110
public constructor(options: IMarkdownDocumenterOptions) {
109111
this._apiModel = options.apiModel;
110112
this._documenterConfig = options.documenterConfig;
111113
this._outputFolder = options.outputFolder;
114+
this._addFileNameSuffix = options.addFileNameSuffix;
112115
this._tsdocConfiguration = CustomDocNodes.configuration;
113116
this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
114117

@@ -123,7 +126,7 @@ export class MarkdownDocumenter {
123126
outputFolder: this._outputFolder,
124127
documenter: new MarkdownDocumenterAccessor({
125128
getLinkForApiItem: (apiItem: ApiItem) => {
126-
return getLinkForApiItem(apiItem);
129+
return getLinkForApiItem(apiItem, this._addFileNameSuffix);
127130
}
128131
})
129132
});
@@ -156,7 +159,7 @@ export class MarkdownDocumenter {
156159
// write to file
157160
const filename: string = path.join(
158161
this._outputFolder,
159-
getFilenameForApiItem(apiItem)
162+
getFilenameForApiItem(apiItem, this._addFileNameSuffix)
160163
);
161164
const stringBuilder: StringBuilder = new StringBuilder();
162165

@@ -172,7 +175,7 @@ export class MarkdownDocumenter {
172175
this._markdownEmitter.emit(stringBuilder, output, {
173176
contextApiItem: apiItem,
174177
onGetFilenameForApiItem: (apiItemForFilename: ApiItem) => {
175-
return getLinkForApiItem(apiItemForFilename);
178+
return getLinkForApiItem(apiItemForFilename, this._addFileNameSuffix);
176179
}
177180
});
178181

@@ -393,7 +396,11 @@ export class MarkdownDocumenter {
393396
case ApiItemKind.Constructor: {
394397
constructorsTable.addRow(
395398
new DocTableRow({ configuration }, [
396-
createTitleCell(apiMember, configuration),
399+
createTitleCell(
400+
apiMember,
401+
configuration,
402+
this._addFileNameSuffix
403+
),
397404
createModifiersCell(apiMember, configuration),
398405
createDescriptionCell(apiMember, configuration)
399406
])
@@ -407,7 +414,11 @@ export class MarkdownDocumenter {
407414
case ApiItemKind.Method: {
408415
methodsTable.addRow(
409416
new DocTableRow({ configuration }, [
410-
createTitleCell(apiMember, configuration),
417+
createTitleCell(
418+
apiMember,
419+
configuration,
420+
this._addFileNameSuffix
421+
),
411422
createModifiersCell(apiMember, configuration),
412423
createDescriptionCell(apiMember, configuration)
413424
])
@@ -422,7 +433,11 @@ export class MarkdownDocumenter {
422433
if ((apiMember as ApiPropertyItem).isEventProperty) {
423434
eventsTable.addRow(
424435
new DocTableRow({ configuration }, [
425-
createTitleCell(apiMember, configuration),
436+
createTitleCell(
437+
apiMember,
438+
configuration,
439+
this._addFileNameSuffix
440+
),
426441
createModifiersCell(apiMember, configuration),
427442
this._createPropertyTypeCell(apiMember),
428443
createDescriptionCell(apiMember, configuration)
@@ -435,7 +450,11 @@ export class MarkdownDocumenter {
435450
} else {
436451
propertiesTable.addRow(
437452
new DocTableRow({ configuration }, [
438-
createTitleCell(apiMember, configuration),
453+
createTitleCell(
454+
apiMember,
455+
configuration,
456+
this._addFileNameSuffix
457+
),
439458
createModifiersCell(apiMember, configuration),
440459
this._createPropertyTypeCell(apiMember),
441460
createDescriptionCell(apiMember, configuration)
@@ -509,7 +528,11 @@ export class MarkdownDocumenter {
509528
case ApiItemKind.MethodSignature: {
510529
methodsTable.addRow(
511530
new DocTableRow({ configuration }, [
512-
createTitleCell(apiMember, configuration),
531+
createTitleCell(
532+
apiMember,
533+
configuration,
534+
this._addFileNameSuffix
535+
),
513536
createDescriptionCell(apiMember, configuration)
514537
])
515538
);
@@ -523,7 +546,11 @@ export class MarkdownDocumenter {
523546
if ((apiMember as ApiPropertyItem).isEventProperty) {
524547
eventsTable.addRow(
525548
new DocTableRow({ configuration }, [
526-
createTitleCell(apiMember, configuration),
549+
createTitleCell(
550+
apiMember,
551+
configuration,
552+
this._addFileNameSuffix
553+
),
527554
this._createPropertyTypeCell(apiMember),
528555
createDescriptionCell(apiMember, configuration)
529556
])
@@ -534,7 +561,11 @@ export class MarkdownDocumenter {
534561
} else {
535562
propertiesTable.addRow(
536563
new DocTableRow({ configuration }, [
537-
createTitleCell(apiMember, configuration),
564+
createTitleCell(
565+
apiMember,
566+
configuration,
567+
this._addFileNameSuffix
568+
),
538569
this._createPropertyTypeCell(apiMember),
539570
createDescriptionCell(apiMember, configuration)
540571
])
@@ -686,7 +717,10 @@ export class MarkdownDocumenter {
686717
configuration,
687718
tagName: '@link',
688719
linkText: unwrappedTokenText,
689-
urlDestination: getLinkForApiItem(apiItemResult.resolvedApiItem)
720+
urlDestination: getLinkForApiItem(
721+
apiItemResult.resolvedApiItem,
722+
this._addFileNameSuffix
723+
)
690724
})
691725
);
692726
continue;
@@ -714,7 +748,7 @@ export class MarkdownDocumenter {
714748

715749
for (const apiMember of apiModel.members) {
716750
const row: DocTableRow = new DocTableRow({ configuration }, [
717-
createTitleCell(apiMember, configuration),
751+
createTitleCell(apiMember, configuration, this._addFileNameSuffix),
718752
createDescriptionCell(apiMember, configuration)
719753
]);
720754

@@ -755,7 +789,11 @@ export class MarkdownDocumenter {
755789

756790
for (const entryPoint of apiContainer.entryPoints) {
757791
const row: DocTableRow = new DocTableRow({ configuration }, [
758-
createEntryPointTitleCell(entryPoint, configuration),
792+
createEntryPointTitleCell(
793+
entryPoint,
794+
configuration,
795+
this._addFileNameSuffix
796+
),
759797
createDescriptionCell(entryPoint, configuration)
760798
]);
761799

@@ -828,7 +866,7 @@ export class MarkdownDocumenter {
828866

829867
for (const apiMember of apiMembers) {
830868
const row: DocTableRow = new DocTableRow({ configuration }, [
831-
createTitleCell(apiMember, configuration),
869+
createTitleCell(apiMember, configuration, this._addFileNameSuffix),
832870
createDescriptionCell(apiMember, configuration)
833871
]);
834872

repo-scripts/api-documenter/src/documenters/MarkdownDocumenterHelpers.ts

+23-9
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,19 @@ import { DocNoteBox } from '../nodes/DocNoteBox';
4949
import { DocTableRow } from '../nodes/DocTableRow';
5050
import { DocTableCell } from '../nodes/DocTableCell';
5151

52-
export function getLinkForApiItem(apiItem: ApiItem) {
53-
const fileName = getFilenameForApiItem(apiItem);
52+
export function getLinkForApiItem(
53+
apiItem: ApiItem,
54+
addFileNameSuffix: boolean
55+
) {
56+
const fileName = getFilenameForApiItem(apiItem, addFileNameSuffix);
5457
const headingAnchor = getHeadingAnchorForApiItem(apiItem);
5558
return `./${fileName}#${headingAnchor}`;
5659
}
5760

58-
export function getFilenameForApiItem(apiItem: ApiItem): string {
61+
export function getFilenameForApiItem(
62+
apiItem: ApiItem,
63+
addFileNameSuffix: boolean
64+
): string {
5965
if (apiItem.kind === ApiItemKind.Model) {
6066
return 'index.md';
6167
}
@@ -103,10 +109,16 @@ export function getFilenameForApiItem(apiItem: ApiItem): string {
103109
// Sometimes we could have a class/interface and an entry point that have the same name.
104110
// This happened in the admin SDK where the App interface and the app namespace write to the same file.
105111
case ApiItemKind.Class:
106-
baseName += '.' + qualifiedName + '_c';
112+
baseName += '.' + qualifiedName;
113+
if (addFileNameSuffix) {
114+
baseName += '_c';
115+
}
107116
break;
108117
case ApiItemKind.Interface:
109-
baseName += '.' + qualifiedName + '_i';
118+
baseName += '.' + qualifiedName;
119+
if (addFileNameSuffix) {
120+
baseName += '_i';
121+
}
110122
break;
111123
}
112124
}
@@ -233,15 +245,16 @@ export function createExampleSection(
233245

234246
export function createTitleCell(
235247
apiItem: ApiItem,
236-
configuration: TSDocConfiguration
248+
configuration: TSDocConfiguration,
249+
addFileNameSuffix: boolean
237250
): DocTableCell {
238251
return new DocTableCell({ configuration }, [
239252
new DocParagraph({ configuration }, [
240253
new DocLinkTag({
241254
configuration,
242255
tagName: '@link',
243256
linkText: Utilities.getConciseSignature(apiItem),
244-
urlDestination: getLinkForApiItem(apiItem)
257+
urlDestination: getLinkForApiItem(apiItem, addFileNameSuffix)
245258
})
246259
])
247260
]);
@@ -348,15 +361,16 @@ export function createThrowsSection(
348361

349362
export function createEntryPointTitleCell(
350363
apiItem: ApiEntryPoint,
351-
configuration: TSDocConfiguration
364+
configuration: TSDocConfiguration,
365+
addFileNameSuffix: boolean
352366
): DocTableCell {
353367
return new DocTableCell({ configuration }, [
354368
new DocParagraph({ configuration }, [
355369
new DocLinkTag({
356370
configuration,
357371
tagName: '@link',
358372
linkText: `/${apiItem.displayName}`,
359-
urlDestination: getLinkForApiItem(apiItem)
373+
urlDestination: getLinkForApiItem(apiItem, addFileNameSuffix)
360374
})
361375
])
362376
]);

0 commit comments

Comments
 (0)