Skip to content

Commit 15388bd

Browse files
Vitalius1octogonz
Vitalius1
authored and
octogonz
committed
Add some types to the new logic
1 parent b37f5fa commit 15388bd

File tree

3 files changed

+182
-23
lines changed

3 files changed

+182
-23
lines changed

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

Lines changed: 24 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ import {
4242
} from '../yaml/IYamlApiFile';
4343
import {
4444
IYamlTocFile,
45-
IYamlTocItem
45+
IYamlTocItem,
46+
IYamlTocConfigSchema
4647
} from '../yaml/IYamlTocFile';
4748
import { Utilities } from '../utils/Utilities';
4849
import { CustomMarkdownEmitter} from '../markdown/CustomMarkdownEmitter';
@@ -65,14 +66,9 @@ export class YamlDocumenter {
6566

6667
private _outputFolder: string;
6768

68-
// ideally the types needs to be an interface with a defined shape a config file can take.
69-
// And whoever creates the config should use it to leverage the type safety.
70-
// tslint:disable-next-line: no-any
71-
private _config: any;
72-
// tslint:disable-next-line: no-any
73-
private _tocPointerMap: any; // type could be an indexer
74-
// tslint:disable-next-line: no-any
75-
private _catchAllPointer: any;
69+
private _config: IYamlTocConfigSchema;
70+
private _tocPointerMap: { [key: string]: IYamlTocItem };
71+
private _catchAllPointer: IYamlTocItem;
7672

7773
public constructor(apiModel: ApiModel) {
7874
this._apiModel = apiModel;
@@ -250,11 +246,16 @@ export class YamlDocumenter {
250246
// Filtering out the api-items as we build the tocItems array.
251247
if (apiItem instanceof ApiDocumentedItem) {
252248
const docInlineTag: DocInlineTag | undefined =
253-
(this._config && this._config.filterByInlineTag) &&
254-
this._findInlineTagByName(this._config.filterByInlineTag, apiItem.tsdocComment);
249+
(this._config && this._config.filterByInlineTag)
250+
? this._findInlineTagByName(this._config.filterByInlineTag, apiItem.tsdocComment)
251+
: undefined;
255252

256-
if (docInlineTag !== undefined && this._tocPointerMap[docInlineTag.tagContent.trim()]) {
257-
this._tocPointerMap[docInlineTag.tagContent.trim()].items.push(tocItem);
253+
const tagContent: string | undefined =
254+
docInlineTag && docInlineTag.tagContent && docInlineTag.tagContent.trim();
255+
256+
if (tagContent && this._tocPointerMap[tagContent]) {
257+
// null assertion used because when pointer map was created we checked for presence of empty `items` array
258+
this._tocPointerMap[tagContent].items!.push(tocItem);
258259
} else {
259260
if (this._catchAllPointer && this._catchAllPointer.items) {
260261
this._catchAllPointer.items.push(tocItem);
@@ -709,17 +710,18 @@ export class YamlDocumenter {
709710
}
710711

711712
// Parses the tocConfig object to build a pointers map of nodes where we want to sort out the API items
712-
// tslint:disable-next-line: no-any
713-
private _generateTocPointersMap(tocConfig: any): void {
714-
for (const tocItem of tocConfig.items) {
715-
if (tocItem.items && tocItem.items.length > 0) {
713+
private _generateTocPointersMap(tocConfig: IYamlTocFile | IYamlTocItem): void {
714+
if (tocConfig.items) {
715+
for (const tocItem of tocConfig.items) {
716+
if (tocItem.items && tocItem.items.length > 0) {
716717
this._generateTocPointersMap(tocItem);
717-
} else {
718-
// check for presence of the `catchAllCategory` config option
719-
if (this._config && this._config.catchAllCategory && tocItem.name === this._config.catchAllCategory) {
720-
this._catchAllPointer = tocItem;
721718
} else {
722-
this._tocPointerMap[tocItem.name] = tocItem;
719+
// check for presence of the `catchAllCategory` config option
720+
if (this._config && this._config.catchAllCategory && tocItem.name === this._config.catchAllCategory) {
721+
this._catchAllPointer = tocItem;
722+
} else {
723+
this._tocPointerMap[tocItem.name] = tocItem;
724+
}
723725
}
724726
}
725727
}

‎apps/api-documenter/src/yaml/IYamlTocFile.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,42 @@ export interface IYamlTocFile {
3434
items: IYamlTocItem[];
3535
metadata?: { [key: string]: string };
3636
}
37+
38+
/**
39+
* Typescript interface describing the config schema for toc.yml file format.
40+
*/
41+
export interface IYamlTocConfigSchema {
42+
/**
43+
* Represents the tree structure describing the toc.file format.
44+
* Only the nodes that have an empty `items` array will be filled with API items
45+
* that are matched with the filters provided. Everything else will be placed under a catchAll category
46+
* that is highly recommended to be provided.
47+
*/
48+
tocConfig: IYamlTocFile;
49+
50+
/**
51+
* Optional category name that is recommended to include in the `tocConfig`,
52+
* along with one of the filters: `filterByApiItemName` or `filterByInlineTag`.
53+
* Any items that are not matched to the mentioned filters will be placed under this
54+
* catchAll category. If none provided the items will not be included in the final toc.yml file.
55+
*/
56+
catchAllCategory?: string;
57+
58+
/**
59+
* When loading more than one api.json files that might include the same API items,
60+
* toggle either to show duplicates or not.
61+
*/
62+
noDuplicateEntries?: boolean;
63+
64+
/**
65+
* Toggle either sorting of the API items should be made based on category name presence
66+
* in the API item's name.
67+
*/
68+
filterByApiItemName?: boolean;
69+
70+
/**
71+
* Filter that can be used to sort the API items according to an inline custom tag
72+
* that is present on them.
73+
*/
74+
filterByInlineTag?: string;
75+
}

‎build-tests/api-documenter-oufr/api-documenter.json‎

Lines changed: 119 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,119 @@
1-
{"tocConfig":{"items":[{"name":"Office UI Fabric React","href":"~/homepage/homepage.md"},{"name":"Office UI Fabric React","href":"office-ui-fabric-react","extended":true,"items":[{"name":"Basic Inputs","items":[{"name":"Button","items":[]},{"name":"Checkbox","items":[]},{"name":"ChoiceGroup","items":[]},{"name":"ComboBox","items":[]},{"name":"Dropdown","items":[]},{"name":"Label","items":[]},{"name":"Link","items":[]},{"name":"Rating","items":[]},{"name":"SearchBox","items":[]},{"name":"Slider","items":[]},{"name":"SpinButton","items":[]},{"name":"TextField","items":[]},{"name":"Toggle","items":[]}]},{"name":"Galleries & Pickers","items":[{"name":"Pickers","items":[]},{"name":"Calendar","items":[]},{"name":"ColorPicker","items":[]},{"name":"DatePicker","items":[]},{"name":"PeoplePicker","items":[]},{"name":"SwatchColorPicker","items":[]}]},{"name":"Items & Lists","items":[{"name":"List","items":[]},{"name":"DetailsList","items":[]},{"name":"GroupedList","items":[]},{"name":"ActivityItem","items":[]},{"name":"DocumentCard","items":[]},{"name":"Facepile","items":[]},{"name":"HoverCard","items":[]},{"name":"Persona","items":[]}]},{"name":"Commands, Menus & Navs","items":[{"name":"Breadcrumb","items":[]},{"name":"CommandBar","items":[]},{"name":"ContextualMenu","items":[]},{"name":"Nav","items":[]},{"name":"OverflowSet","items":[]},{"name":"Pivot","items":[]}]},{"name":"Notification & Engagement","items":[{"name":"Coachmark","items":[]},{"name":"MessageBar","items":[]},{"name":"TeachingBubble","items":[]}]},{"name":"Progress","items":[{"name":"ProgressIndicator","items":[]},{"name":"Shimmer","items":[]},{"name":"Spinner","items":[]}]},{"name":"Surfaces","items":[{"name":"Callout","items":[]},{"name":"Dialog","items":[]},{"name":"Modal","items":[]},{"name":"Panel","items":[]},{"name":"ScrollablePane","items":[]},{"name":"Tooltip","items":[]}]},{"name":"Utilities","items":[{"name":"Announced","items":[]},{"name":"FocusTrapZone","items":[]},{"name":"FocusZone","items":[]},{"name":"Icon","items":[]},{"name":"Image","items":[]},{"name":"Keytips","items":[]},{"name":"Layer","items":[]},{"name":"MarqueeSelection","items":[]},{"name":"Overlay","items":[]},{"name":"ResizeGroup","items":[]},{"name":"Selection","items":[]},{"name":"Separator","items":[]},{"name":"Stack","items":[]},{"name":"Text","items":[]},{"name":"Themes","items":[]}]},{"name":"References","items":[]}]}]},"catchAllCategory":"References","noDuplicateEntries":true,"filterByApiItemName":false,"filterByInlineTag":"@docCategory"}
1+
{
2+
"tocConfig": {
3+
"items": [
4+
{ "name": "Office UI Fabric React", "href": "~/homepage/homepage.md" },
5+
{
6+
"name": "Office UI Fabric React",
7+
"href": "office-ui-fabric-react",
8+
"extended": true,
9+
"items": [
10+
{
11+
"name": "Basic Inputs",
12+
"items": [
13+
{ "name": "Button", "items": [] },
14+
{ "name": "Checkbox", "items": [] },
15+
{ "name": "ChoiceGroup", "items": [] },
16+
{ "name": "ComboBox", "items": [] },
17+
{ "name": "Dropdown", "items": [] },
18+
{ "name": "Label", "items": [] },
19+
{ "name": "Link", "items": [] },
20+
{ "name": "Rating", "items": [] },
21+
{ "name": "SearchBox", "items": [] },
22+
{ "name": "Slider", "items": [] },
23+
{ "name": "SpinButton", "items": [] },
24+
{ "name": "TextField", "items": [] },
25+
{ "name": "Toggle", "items": [] }
26+
]
27+
},
28+
{
29+
"name": "Galleries & Pickers",
30+
"items": [
31+
{ "name": "Pickers", "items": [] },
32+
{ "name": "Calendar", "items": [] },
33+
{ "name": "ColorPicker", "items": [] },
34+
{ "name": "DatePicker", "items": [] },
35+
{ "name": "PeoplePicker", "items": [] },
36+
{ "name": "SwatchColorPicker", "items": [] }
37+
]
38+
},
39+
{
40+
"name": "Items & Lists",
41+
"items": [
42+
{ "name": "List", "items": [] },
43+
{ "name": "DetailsList", "items": [] },
44+
{ "name": "GroupedList", "items": [] },
45+
{ "name": "ActivityItem", "items": [] },
46+
{ "name": "DocumentCard", "items": [] },
47+
{ "name": "Facepile", "items": [] },
48+
{ "name": "HoverCard", "items": [] },
49+
{ "name": "Persona", "items": [] }
50+
]
51+
},
52+
{
53+
"name": "Commands, Menus & Navs",
54+
"items": [
55+
{ "name": "Breadcrumb", "items": [] },
56+
{ "name": "CommandBar", "items": [] },
57+
{ "name": "ContextualMenu", "items": [] },
58+
{ "name": "Nav", "items": [] },
59+
{ "name": "OverflowSet", "items": [] },
60+
{ "name": "Pivot", "items": [] }
61+
]
62+
},
63+
{
64+
"name": "Notification & Engagement",
65+
"items": [
66+
{ "name": "Coachmark", "items": [] },
67+
{ "name": "MessageBar", "items": [] },
68+
{ "name": "TeachingBubble", "items": [] }
69+
]
70+
},
71+
{
72+
"name": "Progress",
73+
"items": [
74+
{ "name": "ProgressIndicator", "items": [] },
75+
{ "name": "Shimmer", "items": [] },
76+
{ "name": "Spinner", "items": [] }
77+
]
78+
},
79+
{
80+
"name": "Surfaces",
81+
"items": [
82+
{ "name": "Callout", "items": [] },
83+
{ "name": "Dialog", "items": [] },
84+
{ "name": "Modal", "items": [] },
85+
{ "name": "Panel", "items": [] },
86+
{ "name": "ScrollablePane", "items": [] },
87+
{ "name": "Tooltip", "items": [] }
88+
]
89+
},
90+
{
91+
"name": "Utilities",
92+
"items": [
93+
{ "name": "Announced", "items": [] },
94+
{ "name": "FocusTrapZone", "items": [] },
95+
{ "name": "FocusZone", "items": [] },
96+
{ "name": "Icon", "items": [] },
97+
{ "name": "Image", "items": [] },
98+
{ "name": "Keytips", "items": [] },
99+
{ "name": "Layer", "items": [] },
100+
{ "name": "MarqueeSelection", "items": [] },
101+
{ "name": "Overlay", "items": [] },
102+
{ "name": "ResizeGroup", "items": [] },
103+
{ "name": "Selection", "items": [] },
104+
{ "name": "Separator", "items": [] },
105+
{ "name": "Stack", "items": [] },
106+
{ "name": "Text", "items": [] },
107+
{ "name": "Themes", "items": [] }
108+
]
109+
},
110+
{ "name": "References", "items": [] }
111+
]
112+
}
113+
]
114+
},
115+
"catchAllCategory": "References",
116+
"noDuplicateEntries": true,
117+
"filterByApiItemName": false,
118+
"filterByInlineTag": "@docCategory"
119+
}

0 commit comments

Comments
 (0)