forked from microsoft/rushstack
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathBaseAction.ts
More file actions
135 lines (116 loc) · 4.75 KB
/
Copy pathBaseAction.ts
File metadata and controls
135 lines (116 loc) · 4.75 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
import * as path from 'path';
import * as tsdoc from '@microsoft/tsdoc';
import colors from 'colors';
import { CommandLineAction, CommandLineStringParameter } from '@rushstack/ts-command-line';
import { FileSystem } from '@rushstack/node-core-library';
import {
ApiModel,
ApiItem,
ApiItemContainerMixin,
ApiDocumentedItem,
IResolveDeclarationReferenceResult
} from '@microsoft/api-extractor-model';
export interface IBuildApiModelResult {
apiModel: ApiModel;
inputFolder: string;
outputFolder: string;
}
export abstract class BaseAction extends CommandLineAction {
private _inputFolderParameter!: CommandLineStringParameter;
private _outputFolderParameter!: CommandLineStringParameter;
protected onDefineParameters(): void {
// override
this._inputFolderParameter = this.defineStringParameter({
parameterLongName: '--input-folder',
parameterShortName: '-i',
argumentName: 'FOLDER1',
description:
`Specifies the input folder containing the *.api.json files to be processed.` +
` If omitted, the default is "./input"`
});
this._outputFolderParameter = this.defineStringParameter({
parameterLongName: '--output-folder',
parameterShortName: '-o',
argumentName: 'FOLDER2',
description:
`Specifies the output folder where the documentation will be written.` +
` ANY EXISTING CONTENTS WILL BE DELETED!` +
` If omitted, the default is "./${this.actionName}"`
});
}
protected buildApiModel(): IBuildApiModelResult {
const apiModel: ApiModel = new ApiModel();
const inputFolder: string = this._inputFolderParameter.value || './input';
if (!FileSystem.exists(inputFolder)) {
throw new Error('The input folder does not exist: ' + inputFolder);
}
const outputFolder: string = this._outputFolderParameter.value || `./${this.actionName}`;
FileSystem.ensureFolder(outputFolder);
for (const filename of FileSystem.readFolderItemNames(inputFolder)) {
if (filename.match(/\.api\.json$/i)) {
console.log(`Reading ${filename}`);
const filenamePath: string = path.join(inputFolder, filename);
apiModel.loadPackage(filenamePath);
}
}
this._applyInheritDoc(apiModel, apiModel);
return { apiModel, inputFolder, outputFolder };
}
// TODO: This is a temporary workaround. The long term plan is for API Extractor's DocCommentEnhancer
// to apply all @inheritDoc tags before the .api.json file is written.
// See DocCommentEnhancer._applyInheritDoc() for more info.
private _applyInheritDoc(apiItem: ApiItem, apiModel: ApiModel): void {
if (apiItem instanceof ApiDocumentedItem) {
if (apiItem.tsdocComment) {
const inheritDocTag: tsdoc.DocInheritDocTag | undefined = apiItem.tsdocComment.inheritDocTag;
if (inheritDocTag && inheritDocTag.declarationReference) {
// Attempt to resolve the declaration reference
const result: IResolveDeclarationReferenceResult = apiModel.resolveDeclarationReference(
inheritDocTag.declarationReference,
apiItem
);
if (result.errorMessage) {
console.log(
colors.yellow(
`Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: ` + result.errorMessage
)
);
} else {
if (
result.resolvedApiItem instanceof ApiDocumentedItem &&
result.resolvedApiItem.tsdocComment &&
result.resolvedApiItem !== apiItem
) {
this._copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);
}
}
}
}
}
// Recurse members
if (ApiItemContainerMixin.isBaseClassOf(apiItem)) {
for (const member of apiItem.members) {
this._applyInheritDoc(member, apiModel);
}
}
}
/**
* Copy the content from `sourceDocComment` to `targetDocComment`.
* This code is borrowed from DocCommentEnhancer as a temporary workaround.
*/
private _copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {
targetDocComment.summarySection = sourceDocComment.summarySection;
targetDocComment.remarksBlock = sourceDocComment.remarksBlock;
targetDocComment.params.clear();
for (const param of sourceDocComment.params) {
targetDocComment.params.add(param);
}
for (const typeParam of sourceDocComment.typeParams) {
targetDocComment.typeParams.add(typeParam);
}
targetDocComment.returnsBlock = sourceDocComment.returnsBlock;
targetDocComment.inheritDocTag = undefined;
}
}