Skip to content

Commit c879dda

Browse files
octogonzoctogonz
authored
Merge pull request microsoft#1295 from raymondfeng/constructor-tsdocs
[api-documenter] Add support for TypeScript constructors
2 parents 2f707b9 + 7daa6a7 commit c879dda

File tree

14 files changed

+237
-5
lines changed

14 files changed

+237
-5
lines changed

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,10 @@ export class MarkdownDocumenter {
9898
case ApiItemKind.Interface:
9999
output.appendNode(new DocHeading({ configuration, title: `${scopedName} interface` }));
100100
break;
101+
case ApiItemKind.Constructor:
102+
case ApiItemKind.ConstructSignature:
103+
output.appendNode(new DocHeading({ configuration, title: scopedName }));
104+
break;
101105
case ApiItemKind.Method:
102106
case ApiItemKind.MethodSignature:
103107
output.appendNode(new DocHeading({ configuration, title: `${scopedName} method` }));
@@ -182,6 +186,8 @@ export class MarkdownDocumenter {
182186
case ApiItemKind.Interface:
183187
this._writeInterfaceTables(output, apiItem as ApiInterface);
184188
break;
189+
case ApiItemKind.Constructor:
190+
case ApiItemKind.ConstructSignature:
185191
case ApiItemKind.Method:
186192
case ApiItemKind.MethodSignature:
187193
case ApiItemKind.Function:
@@ -376,6 +382,10 @@ export class MarkdownDocumenter {
376382
headerTitles: [ 'Property', 'Modifiers', 'Type', 'Description' ]
377383
});
378384

385+
const constructorsTable: DocTable = new DocTable({ configuration,
386+
headerTitles: [ 'Constructor', 'Modifiers', 'Description' ]
387+
});
388+
379389
const propertiesTable: DocTable = new DocTable({ configuration,
380390
headerTitles: [ 'Property', 'Modifiers', 'Type', 'Description' ]
381391
});
@@ -387,6 +397,18 @@ export class MarkdownDocumenter {
387397
for (const apiMember of apiClass.members) {
388398

389399
switch (apiMember.kind) {
400+
case ApiItemKind.Constructor: {
401+
constructorsTable.addRow(
402+
new DocTableRow({ configuration }, [
403+
this._createTitleCell(apiMember),
404+
this._createModifiersCell(apiMember),
405+
this._createDescriptionCell(apiMember)
406+
])
407+
);
408+
409+
this._writeApiItemPage(apiMember);
410+
break;
411+
}
390412
case ApiItemKind.Method: {
391413
methodsTable.addRow(
392414
new DocTableRow({ configuration }, [
@@ -433,6 +455,11 @@ export class MarkdownDocumenter {
433455
output.appendNode(eventsTable);
434456
}
435457

458+
if (constructorsTable.rows.length > 0) {
459+
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Constructors' }));
460+
output.appendNode(constructorsTable);
461+
}
462+
436463
if (propertiesTable.rows.length > 0) {
437464
output.appendNode(new DocHeading({ configuration: this._tsdocConfiguration, title: 'Properties' }));
438465
output.appendNode(propertiesTable);
@@ -502,6 +529,7 @@ export class MarkdownDocumenter {
502529
for (const apiMember of apiClass.members) {
503530

504531
switch (apiMember.kind) {
532+
case ApiItemKind.ConstructSignature:
505533
case ApiItemKind.MethodSignature: {
506534
methodsTable.addRow(
507535
new DocTableRow({ configuration }, [

‎apps/api-extractor-model/src/items/ApiItem.ts‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -107,9 +107,9 @@ export class ApiItem {
107107
*/
108108
public get displayName(): string {
109109
switch (this.kind) {
110-
case ApiItemKind.CallSignature: return '(call signature)';
110+
case ApiItemKind.CallSignature: return '(call)';
111111
case ApiItemKind.Constructor: return '(constructor)';
112-
case ApiItemKind.ConstructSignature: return '(construct signature)';
112+
case ApiItemKind.ConstructSignature: return '(new)';
113113
case ApiItemKind.IndexSignature: return '(indexer)';
114114
case ApiItemKind.Model: return '(model)';
115115
}
@@ -166,8 +166,19 @@ export class ApiItem {
166166
}
167167
if (reversedParts.length !== 0) {
168168
reversedParts.push('.');
169-
} else if (ApiParameterListMixin.isBaseClassOf(current)) { // tslint:disable-line:no-use-before-declare
170-
reversedParts.push('()');
169+
} else {
170+
switch (current.kind) {
171+
case ApiItemKind.CallSignature:
172+
case ApiItemKind.ConstructSignature:
173+
case ApiItemKind.Constructor:
174+
case ApiItemKind.IndexSignature:
175+
// These functional forms don't have a proper name, so we don't append the "()" suffix
176+
break;
177+
default:
178+
if (ApiParameterListMixin.isBaseClassOf(current)) { // tslint:disable-line:no-use-before-declare
179+
reversedParts.push('()');
180+
}
181+
}
171182
}
172183
reversedParts.push(current.displayName);
173184
}

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

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,62 @@
3434
],
3535
"releaseTag": "Public",
3636
"name": "DocBaseClass",
37-
"members": [],
37+
"members": [
38+
{
39+
"kind": "Constructor",
40+
"canonicalReference": "(:constructor,instance,0)",
41+
"docComment": "/**\n * The simple constructor for `DocBaseClass`\n */\n",
42+
"excerptTokens": [
43+
{
44+
"kind": "Content",
45+
"text": "constructor();"
46+
}
47+
],
48+
"isStatic": false,
49+
"releaseTag": "Public",
50+
"overloadIndex": 0,
51+
"parameters": []
52+
},
53+
{
54+
"kind": "Constructor",
55+
"canonicalReference": "(:constructor,instance,1)",
56+
"docComment": "/**\n * The overloaded constructor for `DocBaseClass`\n */\n",
57+
"excerptTokens": [
58+
{
59+
"kind": "Content",
60+
"text": "constructor("
61+
},
62+
{
63+
"kind": "Reference",
64+
"text": "x"
65+
},
66+
{
67+
"kind": "Content",
68+
"text": ": "
69+
},
70+
{
71+
"kind": "Content",
72+
"text": "number"
73+
},
74+
{
75+
"kind": "Content",
76+
"text": ");"
77+
}
78+
],
79+
"isStatic": false,
80+
"releaseTag": "Public",
81+
"overloadIndex": 1,
82+
"parameters": [
83+
{
84+
"parameterName": "x",
85+
"parameterTypeTokenRange": {
86+
"startIndex": 3,
87+
"endIndex": 4
88+
}
89+
}
90+
]
91+
}
92+
],
3893
"implementsTokenRanges": []
3994
},
4095
{

‎build-tests/api-documenter-test/etc/api-documenter-test.api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ export const constVariable: number;
99

1010
// @public
1111
export class DocBaseClass {
12+
constructor();
13+
constructor(x: number);
1214
}
1315

1416
// @public

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass.(constructor).md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [api-documenter-test](./api-documenter-test.md) &gt; [DocBaseClass](./api-documenter-test.docbaseclass.md) &gt; [(constructor)](./api-documenter-test.docbaseclass.(constructor).md)
4+
5+
## DocBaseClass.(constructor)
6+
7+
The simple constructor for `DocBaseClass`
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
constructor();
13+
```

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass.(constructor)_1.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [api-documenter-test](./api-documenter-test.md) &gt; [DocBaseClass](./api-documenter-test.docbaseclass.md) &gt; [(constructor)](./api-documenter-test.docbaseclass.(constructor)_1.md)
4+
5+
## DocBaseClass.(constructor)
6+
7+
The overloaded constructor for `DocBaseClass`
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
constructor(x: number);
13+
```
14+
15+
## Parameters
16+
17+
| Parameter | Type | Description |
18+
| --- | --- | --- |
19+
| x | <code>number</code> | |
20+

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.docbaseclass.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,11 @@ Example base class
1212
```typescript
1313
export declare class DocBaseClass
1414
```
15+
16+
## Constructors
17+
18+
| Constructor | Modifiers | Description |
19+
| --- | --- | --- |
20+
| [(constructor)()](./api-documenter-test.docbaseclass.(constructor).md) | | The simple constructor for <code>DocBaseClass</code> |
21+
| [(constructor)(x)](./api-documenter-test.docbaseclass.(constructor)_1.md) | | The overloaded constructor for <code>DocBaseClass</code> |
22+

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface3.(new).md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
2+
3+
[Home](./index.md) &gt; [api-documenter-test](./api-documenter-test.md) &gt; [IDocInterface3](./api-documenter-test.idocinterface3.md) &gt; [(new)](./api-documenter-test.idocinterface3.(new).md)
4+
5+
## IDocInterface3.(new)
6+
7+
Construct signature
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
new (): IDocInterface1;
13+
```
14+
<b>Returns:</b>
15+
16+
`IDocInterface1`
17+

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface3.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,10 @@ Some less common TypeScript declaration kinds.
1212
```typescript
1313
export interface IDocInterface3
1414
```
15+
16+
## Methods
17+
18+
| Method | Description |
19+
| --- | --- |
20+
| [(new)()](./api-documenter-test.idocinterface3.(new).md) | Construct signature |
21+

‎build-tests/api-documenter-test/etc/yaml/api-documenter-test/docbaseclass.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,29 @@ items:
88
- typeScript
99
type: class
1010
package: api-documenter-test
11+
children:
12+
- api-documenter-test.DocBaseClass.(constructor)
13+
- api-documenter-test.DocBaseClass.(constructor)_1
14+
- uid: api-documenter-test.DocBaseClass.(constructor)
15+
summary: The simple constructor for `DocBaseClass`
16+
name: (constructor)()
17+
fullName: (constructor)()
18+
langs:
19+
- typeScript
20+
type: constructor
21+
syntax:
22+
content: constructor();
23+
- uid: api-documenter-test.DocBaseClass.(constructor)_1
24+
summary: The overloaded constructor for `DocBaseClass`
25+
name: (constructor)(x)
26+
fullName: (constructor)(x)
27+
langs:
28+
- typeScript
29+
type: constructor
30+
syntax:
31+
content: 'constructor(x: number);'
32+
parameters:
33+
- id: x
34+
description: ''
35+
type:
36+
- number

0 commit comments

Comments
 (0)