Skip to content

Commit 5f49ef7

Browse files
octogonzoctogonz
committed
Rename "documentNamespaces" to "newDocfxNamespaces" to make it more clear that this is an opt-in for an experimental DocFX-specific feature
1 parent de86b0f commit 5f49ef7

File tree

9 files changed

+44
-30
lines changed

9 files changed

+44
-30
lines changed

‎apps/api-documenter/src/cli/YamlAction.ts‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import { ApiModel } from '@microsoft/api-extractor-model';
1414

1515
export class YamlAction extends BaseAction {
1616
private _officeParameter: CommandLineFlagParameter;
17-
private _namespacesParameter: CommandLineFlagParameter;
17+
private _newDocfxNamespacesParameter: CommandLineFlagParameter;
1818

1919
public constructor(parser: ApiDocumenterCommandLine) {
2020
super({
@@ -33,10 +33,11 @@ export class YamlAction extends BaseAction {
3333
parameterLongName: '--office',
3434
description: `Enables some additional features specific to Office Add-ins`
3535
});
36-
this._namespacesParameter = this.defineFlagParameter({
37-
parameterLongName: '--namespaces',
38-
description: `Include documentation for namespaces and add them to the TOC.`
39-
+ ` This will also affect file layout as namespaced items will be nested`
36+
this._newDocfxNamespacesParameter = this.defineFlagParameter({
37+
parameterLongName: '--new-docfx-namespaces',
38+
description: `This enables an experimental feature that will be officially released with the next major version`
39+
+ ` of API Documenter. It requires DocFX 2.46 or newer. It enables documentation for namespaces and`
40+
+ ` adds them to the table of contents. This will also affect file layout as namespaced items will be nested`
4041
+ ` under a directory for the namespace instead of just within the package.`
4142
});
4243
}
@@ -45,8 +46,8 @@ export class YamlAction extends BaseAction {
4546
const apiModel: ApiModel = this.buildApiModel();
4647

4748
const yamlDocumenter: YamlDocumenter = this._officeParameter.value
48-
? new OfficeYamlDocumenter(apiModel, this.inputFolder, this._namespacesParameter.value)
49-
: new YamlDocumenter(apiModel, this._namespacesParameter.value);
49+
? new OfficeYamlDocumenter(apiModel, this.inputFolder, this._newDocfxNamespacesParameter.value)
50+
: new YamlDocumenter(apiModel, this._newDocfxNamespacesParameter.value);
5051

5152
yamlDocumenter.generateFiles(this.outputFolder);
5253
return Promise.resolve();

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
1919
private _catchAllPointer: IYamlTocItem;
2020

2121
public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig) {
22-
super(apiModel, documenterConfig.configFile.documentNamespaces);
22+
super(apiModel, documenterConfig.configFile.newDocfxNamespaces);
2323
this._config = documenterConfig.configFile.tableOfContents!;
2424

2525
this._tocPointerMap = {};
@@ -37,7 +37,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
3737
const tocItems: IYamlTocItem[] = [];
3838
for (const apiItem of apiItems) {
3939
let tocItem: IYamlTocItem;
40-
if (apiItem.kind === ApiItemKind.Namespace && !this.documentNamespaces) {
40+
if (apiItem.kind === ApiItemKind.Namespace && !this.newDocfxNamespaces) {
4141
tocItem = {
4242
name: this._getTocItemName(apiItem)
4343
};

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

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -88,13 +88,15 @@ export interface IConfigFile {
8888
newlineKind?: 'crlf' | 'lf' | 'os';
8989

9090
/**
91-
* Include documentation for namespaces and add them to the TOC.
92-
* This will also affect file layout as namespaced items will be nested
91+
* This enables an experimental feature that will be officially released with the next major version
92+
* of API Documenter. It requires DocFX 2.46 or newer. It enables documentation for namespaces and
93+
* adds them to the table of contents. This will also affect file layout as namespaced items will be nested
9394
* under a directory for the namespace instead of just within the package.
9495
*
95-
* This setting currently only affects the 'docfx' output target.
96+
* This setting currently only affects the 'docfx' output target. It is equivalent to the `--new-docfx-namespaces`
97+
* command-line parameter.
9698
*/
97-
documentNamespaces?: boolean;
99+
newDocfxNamespaces?: boolean;
98100

99101
/** {@inheritDoc IConfigPlugin} */
100102
plugins?: IConfigPlugin[];

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
3939
'Word': '/office/dev/add-ins/reference/requirement-sets/word-api-requirement-sets'
4040
};
4141

42-
public constructor(apiModel: ApiModel, inputFolder: string, documentNamespaces?: boolean) {
43-
super(apiModel, documentNamespaces);
42+
public constructor(apiModel: ApiModel, inputFolder: string, newDocfxNamespaces?: boolean) {
43+
super(apiModel, newDocfxNamespaces);
4444

4545
const snippetsFilePath: string = path.join(inputFolder, 'snippets.yaml');
4646

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

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -88,17 +88,17 @@ interface INameOptions {
8888
* Writes documentation in the Universal Reference YAML file format, as defined by typescript.schema.json.
8989
*/
9090
export class YamlDocumenter {
91-
protected readonly documentNamespaces: boolean;
91+
protected readonly newDocfxNamespaces: boolean;
9292
private readonly _apiModel: ApiModel;
9393
private readonly _markdownEmitter: CustomMarkdownEmitter;
9494

9595
private _apiItemsByCanonicalReference: Map<string, ApiItem>;
9696
private _yamlReferences: IYamlReferences | undefined;
9797
private _outputFolder: string;
9898

99-
public constructor(apiModel: ApiModel, documentNamespaces: boolean = false) {
99+
public constructor(apiModel: ApiModel, newDocfxNamespaces: boolean = false) {
100100
this._apiModel = apiModel;
101-
this.documentNamespaces = documentNamespaces;
101+
this.newDocfxNamespaces = newDocfxNamespaces;
102102
this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
103103
this._apiItemsByCanonicalReference = new Map<string, ApiItem>();
104104

@@ -191,7 +191,7 @@ export class YamlDocumenter {
191191
this._recordYamlReference(
192192
this._ensureYamlReferences(),
193193
this._getUid(apiItem),
194-
this._getYamlItemName(apiItem, { includeNamespace: !this.documentNamespaces, includeSignature: true }),
194+
this._getYamlItemName(apiItem, { includeNamespace: !this.newDocfxNamespaces, includeSignature: true }),
195195
this._getYamlItemName(apiItem, { includeNamespace: true, includeSignature: true }));
196196
}
197197
}
@@ -204,10 +204,10 @@ export class YamlDocumenter {
204204
if (apiItem.kind === ApiItemKind.Package) {
205205
// Skip over the entry point, since it's not part of the documentation hierarchy
206206
this._flattenNamespaces(apiItem.members[0].members, children,
207-
this.documentNamespaces ? FlattenMode.NestedNamespacesAndChildren : FlattenMode.NestedChildren);
207+
this.newDocfxNamespaces ? FlattenMode.NestedNamespacesAndChildren : FlattenMode.NestedChildren);
208208
} else {
209209
this._flattenNamespaces(apiItem.members, children,
210-
this.documentNamespaces ? FlattenMode.ImmediateChildren : FlattenMode.NestedChildren);
210+
this.newDocfxNamespaces ? FlattenMode.ImmediateChildren : FlattenMode.NestedChildren);
211211
}
212212
return children;
213213
}
@@ -285,7 +285,7 @@ export class YamlDocumenter {
285285
const tocItems: IYamlTocItem[] = [];
286286
for (const apiItem of apiItems) {
287287
let tocItem: IYamlTocItem;
288-
if (apiItem.kind === ApiItemKind.Namespace && !this.documentNamespaces) {
288+
if (apiItem.kind === ApiItemKind.Namespace && !this.newDocfxNamespaces) {
289289
tocItem = {
290290
name: this._getTocItemName(apiItem)
291291
};
@@ -336,7 +336,7 @@ export class YamlDocumenter {
336336
case ApiItemKind.Enum:
337337
return false;
338338
case ApiItemKind.Namespace:
339-
return !this.documentNamespaces;
339+
return !this.newDocfxNamespaces;
340340
}
341341
return true;
342342
}
@@ -394,14 +394,14 @@ export class YamlDocumenter {
394394
}
395395

396396
yamlItem.name = this._getYamlItemName(apiItem, { includeSignature: true,
397-
includeNamespace: !this.documentNamespaces });
397+
includeNamespace: !this.newDocfxNamespaces });
398398
yamlItem.fullName = this._getYamlItemName(apiItem, { includeSignature: true, includeNamespace: true });
399399
yamlItem.langs = [ 'typeScript' ];
400400

401401
// Add the namespace of the item if it is contained in one.
402402
// Do not add the namespace parent of a namespace as they are flattened in the documentation.
403403
if (apiItem.kind !== ApiItemKind.Namespace && apiItem.parent && apiItem.parent.kind === ApiItemKind.Namespace &&
404-
this.documentNamespaces) {
404+
this.newDocfxNamespaces) {
405405
yamlItem.namespace = apiItem.parent.canonicalReference.toString();
406406
}
407407

‎apps/api-documenter/src/schemas/api-documenter-template.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,17 @@
1919
*/
2020
// "newlineKind": "crlf",
2121

22+
/**
23+
* This enables an experimental feature that will be officially released with the next major version
24+
* of API Documenter. It requires DocFX 2.46 or newer. It enables documentation for namespaces and
25+
* adds them to the table of contents. This will also affect file layout as namespaced items will be nested
26+
* under a directory for the namespace instead of just within the package.
27+
*
28+
* This setting currently only affects the 'docfx' output target. It is equivalent to the `--new-docfx-namespaces`
29+
* command-line parameter.
30+
*/
31+
// "newDocfxNamespaces": false,
32+
2233
/**
2334
* Describes plugin packages to be loaded, and which features to enable.
2435
*/

‎apps/api-documenter/src/schemas/api-documenter.schema.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
"default": "crlf"
2525
},
2626

27-
"documentNamespaces": {
28-
"description": "Include documentation for namespaces and add them to the TOC. 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 setting currently only affects the 'docfx' output target.",
27+
"newDocfxNamespaces": {
28+
"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.",
2929
"type": "boolean"
3030
},
3131

‎build-tests/api-documenter-test/config/api-documenter.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-documenter.schema.json",
3-
"documentNamespaces": true,
3+
"newDocfxNamespaces": true,
44
"newlineKind": "crlf",
55

66
"tableOfContents": {

‎common/changes/@microsoft/api-documenter/flattenNamespaces2_2019-09-22-01-34.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
"changes": [
33
{
44
"packageName": "@microsoft/api-documenter",
5-
"comment": "Include namespaces in YAML output",
5+
"comment": "Add a new command-line option --new-docfx-namespaces to improve how namespaces are represented when generating YAML for DocFX",
66
"type": "minor"
77
}
88
],
99
"packageName": "@microsoft/api-documenter",
10-
"email": "ron.buckton@microsoft.com"
10+
"email": "rbuckton@users.noreply.github.com"
1111
}

0 commit comments

Comments
 (0)