Skip to content

Commit 0aa04b2

Browse files
pgonzalpgonzal
authored
Merge pull request microsoft#1006 from adventure-yunfei/feature/AE7-documenter/support-namespace_function_typealias
[api-documenter] Support more types for markdown
2 parents d84a417 + fdf8569 commit 0aa04b2

10 files changed

+190
-15
lines changed

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

Lines changed: 58 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ import {
2828
ApiEnum,
2929
ApiPackage,
3030
ApiItemKind,
31-
ApiEntryPoint,
3231
ApiReleaseTagMixin,
3332
ApiDocumentedItem,
3433
ApiClass,
@@ -39,7 +38,8 @@ import {
3938
Excerpt,
4039
ApiParameterListMixin,
4140
ApiReturnTypeMixin,
42-
ApiDeclaredItem
41+
ApiDeclaredItem,
42+
ApiNamespace
4343
} from '@microsoft/api-extractor';
4444

4545
import { CustomDocNodes } from '../nodes/CustomDocNodeKind';
@@ -102,6 +102,9 @@ export class MarkdownDocumenter {
102102
case ApiItemKind.MethodSignature:
103103
output.appendNode(new DocHeading({ configuration, title: `${scopedName} method` }));
104104
break;
105+
case ApiItemKind.Function:
106+
output.appendNode(new DocHeading({ configuration, title: `${scopedName} function` }));
107+
break;
105108
case ApiItemKind.Namespace:
106109
output.appendNode(new DocHeading({ configuration, title: `${scopedName} namespace` }));
107110
break;
@@ -113,6 +116,12 @@ export class MarkdownDocumenter {
113116
case ApiItemKind.PropertySignature:
114117
output.appendNode(new DocHeading({ configuration, title: `${scopedName} property` }));
115118
break;
119+
case ApiItemKind.TypeAlias:
120+
output.appendNode(new DocHeading({ configuration, title: `${scopedName} type` }));
121+
break;
122+
case ApiItemKind.Variable:
123+
output.appendNode(new DocHeading({ configuration, title: `${scopedName} variable` }));
124+
break;
116125
default:
117126
throw new Error('Unsupported API item kind: ' + apiItem.kind);
118127
}
@@ -177,14 +186,21 @@ export class MarkdownDocumenter {
177186
case ApiItemKind.MethodSignature:
178187
this._writeParameterTables(output, apiItem as ApiParameterListMixin);
179188
break;
189+
case ApiItemKind.Function:
190+
break;
180191
case ApiItemKind.Namespace:
192+
this._writePackageOrNamespaceTables(output, apiItem as ApiNamespace);
181193
break;
182194
case ApiItemKind.Package:
183-
this._writePackageTables(output, apiItem as ApiPackage);
195+
this._writePackageOrNamespaceTables(output, apiItem as ApiPackage);
184196
break;
185197
case ApiItemKind.Property:
186198
case ApiItemKind.PropertySignature:
187199
break;
200+
case ApiItemKind.TypeAlias:
201+
break;
202+
case ApiItemKind.Variable:
203+
break;
188204
default:
189205
throw new Error('Unsupported API item kind: ' + apiItem.kind);
190206
}
@@ -232,9 +248,9 @@ export class MarkdownDocumenter {
232248
}
233249

234250
/**
235-
* GENERATE PAGE: PACKAGE
251+
* GENERATE PAGE: PACKAGE or NAMESPACE
236252
*/
237-
private _writePackageTables(output: DocSection, apiPackage: ApiPackage): void {
253+
private _writePackageOrNamespaceTables(output: DocSection, apiContainer: ApiPackage | ApiNamespace): void {
238254
const configuration: TSDocConfiguration = this._tsdocConfiguration;
239255

240256
const classesTable: DocTable = new DocTable({ configuration,
@@ -257,9 +273,19 @@ export class MarkdownDocumenter {
257273
headerTitles: [ 'Namespace', 'Description' ]
258274
});
259275

260-
const apiEntryPoint: ApiEntryPoint = apiPackage.entryPoints[0];
276+
const variablesTable: DocTable = new DocTable({ configuration,
277+
headerTitles: [ 'Variable', 'Description' ]
278+
});
279+
280+
const typeAliasesTable: DocTable = new DocTable({ configuration,
281+
headerTitles: [ 'Type Alias', 'Description' ]
282+
});
261283

262-
for (const apiMember of apiEntryPoint.members) {
284+
const apiMembers: ReadonlyArray<ApiItem> = apiContainer.kind === ApiItemKind.Package ?
285+
(apiContainer as ApiPackage).entryPoints[0].members
286+
: (apiContainer as ApiNamespace).members;
287+
288+
for (const apiMember of apiMembers) {
263289

264290
const row: DocTableRow = new DocTableRow({ configuration }, [
265291
this._createTitleCell(apiMember),
@@ -282,18 +308,25 @@ export class MarkdownDocumenter {
282308
this._writeApiItemPage(apiMember);
283309
break;
284310

285-
/*
286-
case 'function':
287-
this._writeFunctionPage(docChild);
311+
case ApiItemKind.Namespace:
312+
namespacesTable.addRow(row);
313+
this._writeApiItemPage(apiMember);
288314
break;
289-
case 'enum':
290-
this._writeEnumPage(docChild);
315+
316+
case ApiItemKind.Function:
317+
functionsTable.addRow(row);
318+
this._writeApiItemPage(apiMember);
291319
break;
292-
case ApiItemKind.Namespace:
293-
this._writeNamespacePage(docChild);
320+
321+
case ApiItemKind.TypeAlias:
322+
typeAliasesTable.addRow(row);
323+
this._writeApiItemPage(apiMember);
294324
break;
295-
*/
296325

326+
case ApiItemKind.Variable:
327+
variablesTable.addRow(row);
328+
this._writeApiItemPage(apiMember);
329+
break;
297330
}
298331
}
299332

@@ -320,6 +353,16 @@ export class MarkdownDocumenter {
320353
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Namespaces' }));
321354
output.appendNode(namespacesTable);
322355
}
356+
357+
if (variablesTable.rows.length > 0) {
358+
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Variables' }));
359+
output.appendNode(variablesTable);
360+
}
361+
362+
if (typeAliasesTable.rows.length > 0) {
363+
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Type Aliases' }));
364+
output.appendNode(typeAliasesTable);
365+
}
323366
}
324367

325368
/**

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.constvariable.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [constVariable](./api-extractor-test-05.constvariable.md)
2+
3+
## constVariable variable
4+
5+
An exported variable declaration.
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
constVariable: number
11+
```

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.exampletypealias.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [ExampleTypeAlias](./api-extractor-test-05.exampletypealias.md)
2+
3+
## ExampleTypeAlias type
4+
5+
A type alias
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
export declare type ExampleTypeAlias = Promise<boolean>;
11+
```

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.globalfunction.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [globalFunction](./api-extractor-test-05.globalfunction.md)
2+
3+
## globalFunction() function
4+
5+
An exported function
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
export declare function globalFunction(x: number): number;
11+
```

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,12 @@ This project tests various documentation generation scenarios and doc comment sy
2020
| --- | --- |
2121
| <p>[DocEnum](./api-extractor-test-05.docenum.md)</p> | <p>Docs for DocEnum</p> |
2222

23+
## Functions
24+
25+
| <p>Function</p> | <p>Description</p> |
26+
| --- | --- |
27+
| <p>[globalFunction(x)](./api-extractor-test-05.globalfunction.md)</p> | <p>An exported function</p> |
28+
2329
## Interfaces
2430

2531
| <p>Interface</p> | <p>Description</p> |
@@ -28,3 +34,21 @@ This project tests various documentation generation scenarios and doc comment sy
2834
| <p>[IDocInterface2](./api-extractor-test-05.idocinterface2.md)</p> | <p></p> |
2935
| <p>[IDocInterface3](./api-extractor-test-05.idocinterface3.md)</p> | <p>Some less common TypeScript declaration kinds.</p> |
3036

37+
## Namespaces
38+
39+
| <p>Namespace</p> | <p>Description</p> |
40+
| --- | --- |
41+
| <p>[OuterNamespace](./api-extractor-test-05.outernamespace.md)</p> | <p>A top-level namespace</p> |
42+
43+
## Variables
44+
45+
| <p>Variable</p> | <p>Description</p> |
46+
| --- | --- |
47+
| <p>[constVariable](./api-extractor-test-05.constvariable.md)</p> | <p>An exported variable declaration.</p> |
48+
49+
## Type Aliases
50+
51+
| <p>Type Alias</p> | <p>Description</p> |
52+
| --- | --- |
53+
| <p>[ExampleTypeAlias](./api-extractor-test-05.exampletypealias.md)</p> | <p>A type alias</p> |
54+

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.outernamespace.innernamespace.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [OuterNamespace](./api-extractor-test-05.outernamespace.md) &gt; [InnerNamespace](./api-extractor-test-05.outernamespace.innernamespace.md)
2+
3+
## OuterNamespace.InnerNamespace namespace
4+
5+
A nested namespace
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
namespace InnerNamespace
11+
```
12+
13+
## Functions
14+
15+
| <p>Function</p> | <p>Description</p> |
16+
| --- | --- |
17+
| <p>[nestedFunction(x)](./api-extractor-test-05.outernamespace.innernamespace.nestedfunction.md)</p> | <p>A function inside a namespace</p> |
18+

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.outernamespace.innernamespace.nestedfunction.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [OuterNamespace](./api-extractor-test-05.outernamespace.md) &gt; [InnerNamespace](./api-extractor-test-05.outernamespace.innernamespace.md) &gt; [nestedFunction](./api-extractor-test-05.outernamespace.innernamespace.nestedfunction.md)
2+
3+
## OuterNamespace.InnerNamespace.nestedFunction() function
4+
5+
A function inside a namespace
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
function nestedFunction(x: number): number;
11+
```

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.outernamespace.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [OuterNamespace](./api-extractor-test-05.outernamespace.md)
2+
3+
## OuterNamespace namespace
4+
5+
A top-level namespace
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
export declare namespace OuterNamespace
11+
```
12+
13+
## Namespaces
14+
15+
| <p>Namespace</p> | <p>Description</p> |
16+
| --- | --- |
17+
| <p>[InnerNamespace](./api-extractor-test-05.outernamespace.innernamespace.md)</p> | <p>A nested namespace</p> |
18+
19+
## Variables
20+
21+
| <p>Variable</p> | <p>Description</p> |
22+
| --- | --- |
23+
| <p>[nestedVariable](./api-extractor-test-05.outernamespace.nestedvariable.md)</p> | <p>A variable exported from within a namespace.</p> |
24+

‎build-tests/api-extractor-test-05/etc/markdown/api-extractor-test-05.outernamespace.nestedvariable.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[Home](./index) &gt; [api-extractor-test-05](./api-extractor-test-05.md) &gt; [OuterNamespace](./api-extractor-test-05.outernamespace.md) &gt; [nestedVariable](./api-extractor-test-05.outernamespace.nestedvariable.md)
2+
3+
## OuterNamespace.nestedVariable variable
4+
5+
A variable exported from within a namespace.
6+
7+
<b>Signature:</b>
8+
9+
```typescript
10+
nestedVariable: boolean
11+
```

‎common/changes/@microsoft/api-documenter/feature-AE7-documenter-support-namespace_function_typealias_2018-12-31-04-53.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@microsoft/api-documenter",
5+
"comment": "Support more API types for the markdown generator: namespace, function, type alias, variable",
6+
"type": "patch"
7+
}
8+
],
9+
"packageName": "@microsoft/api-documenter",
10+
"email": "adventure-yunfei@users.noreply.github.com"
11+
}

0 commit comments

Comments
 (0)