@microsoft/api-documenter
Version:
Read JSON files from api-extractor, generate documentation pages
93 lines • 4.64 kB
JavaScript
// 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 'node:path';
import { CommandLineAction } from '@rushstack/ts-command-line';
import { FileSystem } from '@rushstack/node-core-library';
import { ApiModel, ApiItemContainerMixin, ApiDocumentedItem } from '@microsoft/api-extractor-model';
import { Colorize } from '@rushstack/terminal';
export class BaseAction extends CommandLineAction {
constructor(options) {
super(options);
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}"`
});
}
buildApiModel() {
const apiModel = new ApiModel();
const inputFolder = this._inputFolderParameter.value || './input';
if (!FileSystem.exists(inputFolder)) {
throw new Error('The input folder does not exist: ' + inputFolder);
}
const outputFolder = 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 = 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.
_applyInheritDoc(apiItem, apiModel) {
if (apiItem instanceof ApiDocumentedItem) {
if (apiItem.tsdocComment) {
const inheritDocTag = apiItem.tsdocComment.inheritDocTag;
if (inheritDocTag && inheritDocTag.declarationReference) {
// Attempt to resolve the declaration reference
const result = apiModel.resolveDeclarationReference(inheritDocTag.declarationReference, apiItem);
if (result.errorMessage) {
console.log(Colorize.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.
*/
_copyInheritedDocs(targetDocComment, sourceDocComment) {
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;
}
}
//# sourceMappingURL=BaseAction.js.map