Skip to content

Use native private members in core tooling #5943

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Bharat Middha (bmiddha) wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Use native private members in core tooling #5943

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f515d58
refactor: use ECMAScript #private fields
bmiddha Aug 19, 2026
bb9f15c
fix(api-extractor): suppress private null warning
bmiddha Aug 19, 2026
1ba2fc0
refactor: use ECMAScript #private methods and accessors
bmiddha Aug 19, 2026
6740253
fix(eslint-plugin): recognize native privacy
bmiddha Aug 20, 2026
89ef8df
Merge remote-tracking branch 'origin/bmiddha/fix-no-new-null-native-p…
bmiddha Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions apps/api-documenter/src/cli/ApiDocumenterCommandLine.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ export class ApiDocumenterCommandLine extends CommandLineParser {
'Reads *.api.json files produced by api-extractor, ' +
' and generates API documentation in various output formats.'
});
this._populateActions();
this.#populateActions();
}

private _populateActions(): void {
#populateActions(): void {
this.addAction(new MarkdownAction(this));
this.addAction(new YamlAction(this));
this.addAction(new GenerateAction(this));
Expand Down
22 changes: 11 additions & 11 deletions apps/api-documenter/src/cli/BaseAction.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,13 @@ export interface IBuildApiModelResult {
}

export abstract class BaseAction extends CommandLineAction {
private readonly _inputFolderParameter: CommandLineStringParameter;
private readonly _outputFolderParameter: CommandLineStringParameter;
readonly #inputFolderParameter: CommandLineStringParameter;
readonly #outputFolderParameter: CommandLineStringParameter;

protected constructor(options: ICommandLineActionOptions) {
super(options);

this._inputFolderParameter = this.defineStringParameter({
this.#inputFolderParameter = this.defineStringParameter({
parameterLongName: '--input-folder',
parameterShortName: '-i',
argumentName: 'FOLDER1',
Expand All @@ -41,7 +41,7 @@ export abstract class BaseAction extends CommandLineAction {
` If omitted, the default is "./input"`
});

this._outputFolderParameter = this.defineStringParameter({
this.#outputFolderParameter = this.defineStringParameter({
parameterLongName: '--output-folder',
parameterShortName: '-o',
argumentName: 'FOLDER2',
Expand All @@ -55,12 +55,12 @@ export abstract class BaseAction extends CommandLineAction {
protected buildApiModel(): IBuildApiModelResult {
const apiModel: ApiModel = new ApiModel();

const inputFolder: string = this._inputFolderParameter.value || './input';
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}`;
const outputFolder: string = this.#outputFolderParameter.value || `./${this.actionName}`;
FileSystem.ensureFolder(outputFolder);

for (const filename of FileSystem.readFolderItemNames(inputFolder)) {
Expand All @@ -71,15 +71,15 @@ export abstract class BaseAction extends CommandLineAction {
}
}

this._applyInheritDoc(apiModel, apiModel);
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 {
#applyInheritDoc(apiItem: ApiItem, apiModel: ApiModel): void {
if (apiItem instanceof ApiDocumentedItem) {
if (apiItem.tsdocComment) {
const inheritDocTag: tsdoc.DocInheritDocTag | undefined = apiItem.tsdocComment.inheritDocTag;
Expand All @@ -103,7 +103,7 @@ export abstract class BaseAction extends CommandLineAction {
result.resolvedApiItem.tsdocComment &&
result.resolvedApiItem !== apiItem
) {
this._copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);
this.#copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);
}
}
}
Expand All @@ -113,7 +113,7 @@ export abstract class BaseAction extends CommandLineAction {
// Recurse members
if (ApiItemContainerMixin.isBaseClassOf(apiItem)) {
for (const member of apiItem.members) {
this._applyInheritDoc(member, apiModel);
this.#applyInheritDoc(member, apiModel);
}
}
}
Expand All @@ -122,7 +122,7 @@ export abstract class BaseAction extends CommandLineAction {
* 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 {
#copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {
targetDocComment.summarySection = sourceDocComment.summarySection;
targetDocComment.remarksBlock = sourceDocComment.remarksBlock;

Expand Down
20 changes: 10 additions & 10 deletions apps/api-documenter/src/cli/YamlAction.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ import { YamlDocumenter, type YamlFormat } from '../documenters/YamlDocumenter';
import { OfficeYamlDocumenter } from '../documenters/OfficeYamlDocumenter';

export class YamlAction extends BaseAction {
private readonly _officeParameter: CommandLineFlagParameter;
private readonly _newDocfxNamespacesParameter: CommandLineFlagParameter;
private readonly _yamlFormatParameter: IRequiredCommandLineChoiceParameter<YamlFormat>;
readonly #officeParameter: CommandLineFlagParameter;
readonly #newDocfxNamespacesParameter: CommandLineFlagParameter;
readonly #yamlFormatParameter: IRequiredCommandLineChoiceParameter<YamlFormat>;

public constructor(parser: ApiDocumenterCommandLine) {
super({
Expand All @@ -26,19 +26,19 @@ export class YamlAction extends BaseAction {
' pipeline.'
});

this._officeParameter = this.defineFlagParameter({
this.#officeParameter = this.defineFlagParameter({
parameterLongName: '--office',
description: `Enables some additional features specific to Office Add-ins`
});
this._newDocfxNamespacesParameter = this.defineFlagParameter({
this.#newDocfxNamespacesParameter = this.defineFlagParameter({
parameterLongName: '--new-docfx-namespaces',
description:
`This enables an experimental feature that will be officially released with the next major version` +
` of API Documenter. It requires DocFX 2.46 or newer. It enables documentation for namespaces and` +
` adds them to the table of contents. This will also affect file layout as namespaced items will be nested` +
` under a directory for the namespace instead of just within the package.`
});
this._yamlFormatParameter = this.defineChoiceParameter<YamlFormat>({
this.#yamlFormatParameter = this.defineChoiceParameter<YamlFormat>({
parameterLongName: '--yaml-format',
alternatives: ['udp', 'sdp'],
defaultValue: 'sdp',
Expand All @@ -52,12 +52,12 @@ export class YamlAction extends BaseAction {
protected override async onExecuteAsync(): Promise<void> {
const { apiModel, inputFolder, outputFolder } = this.buildApiModel();

const yamlDocumenter: YamlDocumenter = this._officeParameter.value
? new OfficeYamlDocumenter(apiModel, inputFolder, this._newDocfxNamespacesParameter.value)
const yamlDocumenter: YamlDocumenter = this.#officeParameter.value
? new OfficeYamlDocumenter(apiModel, inputFolder, this.#newDocfxNamespacesParameter.value)
: new YamlDocumenter(
apiModel,
this._newDocfxNamespacesParameter.value,
this._yamlFormatParameter.value
this.#newDocfxNamespacesParameter.value,
this.#yamlFormatParameter.value
);

yamlDocumenter.generateFiles(outputFolder);
Expand Down
60 changes: 30 additions & 30 deletions apps/api-documenter/src/documenters/ExperimentalYamlDocumenter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,25 @@ import type { DocumenterConfig } from './DocumenterConfig';
* API Documenter. It is not ready for general usage yet. Its design may change in the future.
*/
export class ExperimentalYamlDocumenter extends YamlDocumenter {
private _config: IConfigTableOfContents;
private _tocPointerMap: { [key: string]: IYamlTocItem };
private _catchAllPointer: IYamlTocItem | undefined;
#config: IConfigTableOfContents;
#tocPointerMap: { [key: string]: IYamlTocItem };
#catchAllPointer: IYamlTocItem | undefined;

public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig) {
super(apiModel, documenterConfig.configFile.newDocfxNamespaces);
this._config = documenterConfig.configFile.tableOfContents!;
this.#config = documenterConfig.configFile.tableOfContents!;

this._tocPointerMap = {};
this.#tocPointerMap = {};

this._generateTocPointersMap(this._config.tocConfig);
this.#generateTocPointersMap(this.#config.tocConfig);
}

protected override buildYamlTocFile(apiItems: ReadonlyArray<ApiItem>): IYamlTocFile {
this._buildTocItems2(apiItems);
return this._config.tocConfig;
this.#buildTocItems2(apiItems);
return this.#config.tocConfig;
}

private _buildTocItems2(apiItems: ReadonlyArray<ApiItem>): IYamlTocItem[] {
#buildTocItems2(apiItems: ReadonlyArray<ApiItem>): IYamlTocItem[] {
const tocItems: IYamlTocItem[] = [];
for (const apiItem of apiItems) {
let tocItem: IYamlTocItem;
Expand All @@ -52,14 +52,14 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
};

if (apiItem.kind !== ApiItemKind.Package) {
this._filterItem(apiItem, tocItem);
this.#filterItem(apiItem, tocItem);
}
}

tocItems.push(tocItem);

const children: ApiItem[] = this._getLogicalChildren(apiItem);
const childItems: IYamlTocItem[] = this._buildTocItems2(children);
const childItems: IYamlTocItem[] = this.#buildTocItems2(children);
if (childItems.length > 0) {
tocItem.items = childItems;
}
Expand All @@ -68,19 +68,19 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
}

// Parses the tocConfig object to build a pointers map of nodes where we want to sort out the API items
private _generateTocPointersMap(tocConfig: IYamlTocFile | IYamlTocItem): void {
const { catchAllCategory } = this._config;
#generateTocPointersMap(tocConfig: IYamlTocFile | IYamlTocItem): void {
const { catchAllCategory } = this.#config;

if (tocConfig.items) {
for (const tocItem of tocConfig.items) {
if (tocItem.items && tocItem.items.length > 0 && this._shouldNotIncludeInPointersMap(tocItem)) {
this._generateTocPointersMap(tocItem);
if (tocItem.items && tocItem.items.length > 0 && this.#shouldNotIncludeInPointersMap(tocItem)) {
this.#generateTocPointersMap(tocItem);
} else {
// check for presence of the `catchAllCategory` config option
if (catchAllCategory && tocItem.name === catchAllCategory) {
this._catchAllPointer = tocItem;
this.#catchAllPointer = tocItem;
} else {
this._tocPointerMap[tocItem.name] = tocItem;
this.#tocPointerMap[tocItem.name] = tocItem;
}
}
}
Expand All @@ -90,49 +90,49 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
/**
* Filtering out the api-item by inlineTags or category name presence in the item name.
*/
private _filterItem(apiItem: ApiItem, tocItem: IYamlTocItem): void {
const { categoryInlineTag, categorizeByName } = this._config;
#filterItem(apiItem: ApiItem, tocItem: IYamlTocItem): void {
const { categoryInlineTag, categorizeByName } = this.#config;
const { name: itemName } = tocItem;
let filtered: boolean = false;

// First we attempt to filter by inline tag if provided.
if (apiItem instanceof ApiDocumentedItem) {
const docInlineTag: DocInlineTag | undefined = categoryInlineTag
? this._findInlineTagByName(categoryInlineTag, apiItem.tsdocComment)
? this.#findInlineTagByName(categoryInlineTag, apiItem.tsdocComment)
: undefined;

const tagContent: string | undefined =
docInlineTag && docInlineTag.tagContent && docInlineTag.tagContent.trim();

if (tagContent && this._tocPointerMap[tagContent]) {
if (tagContent && this.#tocPointerMap[tagContent]) {
// null assertion used because when pointer map was created we checked for presence of empty `items` array
this._tocPointerMap[tagContent].items!.push(tocItem);
this.#tocPointerMap[tagContent].items!.push(tocItem);
filtered = true;
}
}

// If not filtered by inline tag and `categorizeByName` config is enabled attempt to filter it by category name.
if (!filtered && categorizeByName) {
const pointers: string[] = Object.keys(this._tocPointerMap);
const pointers: string[] = Object.keys(this.#tocPointerMap);
for (let i: number = 0, length: number = pointers.length; i < length; i++) {
if (itemName.indexOf(pointers[i]) !== -1) {
// null assertion used because when pointer map was created we checked for presence of empty `items` array
this._tocPointerMap[pointers[i]].items!.push(tocItem);
this.#tocPointerMap[pointers[i]].items!.push(tocItem);
filtered = true;
break;
}
}
}

// If item still not filtered and a `catchAllCategory` config provided push it to it.
if (!filtered && this._catchAllPointer && this._catchAllPointer.items) {
this._catchAllPointer.items.push(tocItem);
if (!filtered && this.#catchAllPointer && this.#catchAllPointer.items) {
this.#catchAllPointer.items.push(tocItem);
}
}

// This is a direct copy of a @docCategory inline tag finder in office-ui-fabric-react,
// but is generic enough to be used for any inline tag
private _findInlineTagByName(
#findInlineTagByName(
tagName: string,
docComment: DocComment | undefined
): DocInlineTag | undefined {
Expand All @@ -145,7 +145,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
}
if (docComment) {
for (const childNode of docComment.getChildNodes()) {
const result: DocInlineTag | undefined = this._findInlineTagByName(tagName, childNode as DocComment);
const result: DocInlineTag | undefined = this.#findInlineTagByName(tagName, childNode as DocComment);
if (result !== undefined) {
return result;
}
Expand All @@ -154,8 +154,8 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
return undefined;
}

private _shouldNotIncludeInPointersMap(item: IYamlTocItem): boolean {
const { nonEmptyCategoryNodeNames } = this._config;
#shouldNotIncludeInPointersMap(item: IYamlTocItem): boolean {
const { nonEmptyCategoryNodeNames } = this.#config;
if (nonEmptyCategoryNodeNames && nonEmptyCategoryNodeNames.length) {
return nonEmptyCategoryNodeNames.indexOf(item.name) === -1;
}
Expand Down
Loading
Loading