Skip to content

Commit 9bc8fe7

Browse files
octogonzoctogonz
authored
[api-extractor] Fix a problem where overload indexes started from 0 instead of 1 (microsoft#1312)
[api-extractor] Fix a problem where overload indexes started from 0 instead of 1
2 parents 01bfda8 + 1bae5d0 commit 9bc8fe7

13 files changed

Lines changed: 125 additions & 16 deletions

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -793,8 +793,10 @@ export class MarkdownDocumenter {
793793
// For overloaded methods, add a suffix such as "MyClass.myMethod_2".
794794
let qualifiedName: string = hierarchyItem.displayName;
795795
if (ApiParameterListMixin.isBaseClassOf(hierarchyItem)) {
796-
if (hierarchyItem.overloadIndex > 0) {
797-
qualifiedName += `_${hierarchyItem.overloadIndex}`;
796+
if (hierarchyItem.overloadIndex > 1) {
797+
// Subtract one for compatibility with earlier releases of API Documenter.
798+
// (This will get revamped when we fix GitHub issue #1308)
799+
qualifiedName += `_${hierarchyItem.overloadIndex - 1}`;
798800
}
799801
}
800802

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -526,8 +526,10 @@ export class YamlDocumenter {
526526
// For overloaded methods, add a suffix such as "MyClass.myMethod_2".
527527
let qualifiedName: string = hierarchyItem.displayName;
528528
if (ApiParameterListMixin.isBaseClassOf(hierarchyItem)) {
529-
if (hierarchyItem.overloadIndex > 0) {
530-
qualifiedName += `_${hierarchyItem.overloadIndex}`;
529+
if (hierarchyItem.overloadIndex > 1) {
530+
// Subtract one for compatibility with earlier releases of API Documenter.
531+
// (This will get revamped when we fix GitHub issue #1308)
532+
qualifiedName += `_${hierarchyItem.overloadIndex - 1}`;
531533
}
532534
}
533535

‎apps/api-extractor-model/src/mixins/ApiParameterListMixin.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,16 +60,21 @@ export interface ApiParameterListMixin extends ApiItem {
6060
*
6161
* ```ts
6262
* export namespace Versioning {
63+
* // TSDoc: Versioning.(addVersions:1)
6364
* export function addVersions(x: number, y: number): number;
65+
*
66+
* // TSDoc: Versioning.(addVersions:2)
6467
* export function addVersions(x: string, y: string): string;
68+
*
69+
* // (implementation)
6570
* export function addVersions(x: number|string, y: number|string): number|string {
6671
* // . . .
6772
* }
6873
* }
6974
* ```
7075
*
7176
* In the above example, there are two overloaded declarations. The overload using numbers will have
72-
* `overloadIndex = 0`. The overload using strings will have `overloadIndex = 1`. The third declaration that
77+
* `overloadIndex = 1`. The overload using strings will have `overloadIndex = 2`. The third declaration that
7378
* accepts all possible inputs is considered part of the implementation, and is not processed by API Extractor.
7479
*/
7580
readonly overloadIndex: number;

‎apps/api-extractor/src/generators/ApiModelGenerator.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -724,7 +724,8 @@ export class ApiModelGenerator {
724724
let overloadIndex: number | undefined = this._cachedOverloadIndexesByDeclaration.get(astDeclaration);
725725

726726
if (overloadIndex === undefined) {
727-
let nextIndex: number = 0;
727+
// TSDoc index selectors are positive integers counting from 1
728+
let nextIndex: number = 1;
728729
for (const other of allDeclarations) {
729730
// Filter out other declarations that are not overloads. For example, an overloaded function can also
730731
// be a namespace.

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

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -37,22 +37,21 @@
3737
"members": [
3838
{
3939
"kind": "Constructor",
40-
"canonicalReference": "(:constructor,instance,0)",
40+
"canonicalReference": "(:constructor,1)",
4141
"docComment": "/**\n * The simple constructor for `DocBaseClass`\n */\n",
4242
"excerptTokens": [
4343
{
4444
"kind": "Content",
4545
"text": "constructor();"
4646
}
4747
],
48-
"isStatic": false,
4948
"releaseTag": "Public",
50-
"overloadIndex": 0,
49+
"overloadIndex": 1,
5150
"parameters": []
5251
},
5352
{
5453
"kind": "Constructor",
55-
"canonicalReference": "(:constructor,instance,1)",
54+
"canonicalReference": "(:constructor,2)",
5655
"docComment": "/**\n * The overloaded constructor for `DocBaseClass`\n */\n",
5756
"excerptTokens": [
5857
{
@@ -76,9 +75,8 @@
7675
"text": ");"
7776
}
7877
],
79-
"isStatic": false,
8078
"releaseTag": "Public",
81-
"overloadIndex": 1,
79+
"overloadIndex": 2,
8280
"parameters": [
8381
{
8482
"parameterName": "x",
@@ -175,7 +173,7 @@
175173
},
176174
{
177175
"kind": "Method",
178-
"canonicalReference": "(exampleFunction:instance,0)",
176+
"canonicalReference": "(exampleFunction:instance,1)",
179177
"docComment": "/**\n * This is an overloaded function.\n *\n * @param a - the first string\n *\n * @param b - the second string\n */\n",
180178
"excerptTokens": [
181179
{
@@ -233,7 +231,7 @@
233231
"endIndex": 11
234232
},
235233
"releaseTag": "Public",
236-
"overloadIndex": 0,
234+
"overloadIndex": 1,
237235
"parameters": [
238236
{
239237
"parameterName": "a",
@@ -254,7 +252,7 @@
254252
},
255253
{
256254
"kind": "Method",
257-
"canonicalReference": "(exampleFunction:instance,1)",
255+
"canonicalReference": "(exampleFunction:instance,2)",
258256
"docComment": "/**\n * This is also an overloaded function.\n *\n * @param x - the number\n */\n",
259257
"excerptTokens": [
260258
{
@@ -296,7 +294,7 @@
296294
"endIndex": 7
297295
},
298296
"releaseTag": "Public",
299-
"overloadIndex": 1,
297+
"overloadIndex": 2,
300298
"parameters": [
301299
{
302300
"parameterName": "x",

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface5.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; [IDocInterface5](./api-documenter-test.idocinterface5.md)
4+
5+
## IDocInterface5 interface
6+
7+
Interface without inline tag to test custom TOC
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
export interface IDocInterface5
13+
```
14+
15+
## Properties
16+
17+
| Property | Type | Description |
18+
| --- | --- | --- |
19+
| [regularProperty](./api-documenter-test.idocinterface5.regularproperty.md) | <code>string</code> | Property of type string that does something |
20+

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface5.regularproperty.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; [IDocInterface5](./api-documenter-test.idocinterface5.md) &gt; [regularProperty](./api-documenter-test.idocinterface5.regularproperty.md)
4+
5+
## IDocInterface5.regularProperty property
6+
7+
Property of type string that does something
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
regularProperty: string;
13+
```

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.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; [IDocInterface6](./api-documenter-test.idocinterface6.md)
4+
5+
## IDocInterface6 interface
6+
7+
Interface without inline tag to test custom TOC with injection
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
export interface IDocInterface6
13+
```
14+
15+
## Properties
16+
17+
| Property | Type | Description |
18+
| --- | --- | --- |
19+
| [regularProperty](./api-documenter-test.idocinterface6.regularproperty.md) | <code>number</code> | Property of type number that does something |
20+

‎build-tests/api-documenter-test/etc/markdown/api-documenter-test.idocinterface6.regularproperty.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; [IDocInterface6](./api-documenter-test.idocinterface6.md) &gt; [regularProperty](./api-documenter-test.idocinterface6.regularproperty.md)
4+
5+
## IDocInterface6.regularProperty property
6+
7+
Property of type number that does something
8+
9+
<b>Signature:</b>
10+
11+
```typescript
12+
regularProperty: number;
13+
```

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ This project tests various documentation generation scenarios and doc comment sy
3737
| [IDocInterface2](./api-documenter-test.idocinterface2.md) | |
3838
| [IDocInterface3](./api-documenter-test.idocinterface3.md) | Some less common TypeScript declaration kinds. |
3939
| [IDocInterface4](./api-documenter-test.idocinterface4.md) | Type union in an interface. |
40+
| [IDocInterface5](./api-documenter-test.idocinterface5.md) | Interface without inline tag to test custom TOC |
41+
| [IDocInterface6](./api-documenter-test.idocinterface6.md) | Interface without inline tag to test custom TOC with injection |
4042

4143
## Namespaces
4244

0 commit comments

Comments
 (0)