Skip to content

Commit 1b1cd14

Browse files
Gerrit0Gerrit0
committed
fix: Correctly handle comments on function type aliases
Resolves #799.
1 parent 1dc5659 commit 1b1cd14

File tree

6 files changed

+101
-79
lines changed

6 files changed

+101
-79
lines changed

‎src/lib/converter/plugins/CommentPlugin.ts‎

Lines changed: 63 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {
77
ReflectionKind,
88
TypeParameterReflection,
99
DeclarationReflection,
10+
SignatureReflection,
1011
} from "../../models/reflections/index";
1112
import { Component, ConverterComponent } from "../components";
1213
import {
@@ -17,7 +18,7 @@ import {
1718
import { Converter } from "../converter";
1819
import { Context } from "../context";
1920
import { partition, uniq } from "lodash";
20-
import { SourceReference } from "../../models";
21+
import { ReflectionType, SourceReference } from "../../models";
2122
import { BindOption, filterMap, removeIfPresent } from "../../utils";
2223

2324
/**
@@ -269,54 +270,74 @@ export class CommentPlugin extends ConverterComponent {
269270
return;
270271
}
271272

272-
const signatures = reflection.getAllSignatures();
273-
if (signatures.length) {
274-
const comment = reflection.comment;
275-
if (comment && comment.hasTag("returns")) {
276-
comment.returns = comment.getTag("returns")!.text;
277-
comment.removeTags("returns");
278-
}
273+
if (reflection.type instanceof ReflectionType) {
274+
this.addCommentToSignatures(
275+
reflection,
276+
reflection.type.declaration.getNonIndexSignatures()
277+
);
278+
} else {
279+
this.addCommentToSignatures(
280+
reflection,
281+
reflection.getNonIndexSignatures()
282+
);
283+
}
284+
}
279285

280-
signatures.forEach((signature) => {
281-
let childComment = signature.comment;
282-
if (childComment && childComment.hasTag("returns")) {
283-
childComment.returns = childComment.getTag("returns")!.text;
284-
childComment.removeTags("returns");
285-
}
286+
private addCommentToSignatures(
287+
reflection: DeclarationReflection,
288+
signatures: SignatureReflection[]
289+
) {
290+
if (!signatures.length) {
291+
return;
292+
}
286293

287-
if (comment) {
288-
if (!childComment) {
289-
childComment = signature.comment = new Comment();
290-
}
294+
let movedComment = false;
295+
const comment = reflection.comment;
296+
if (comment && comment.hasTag("returns")) {
297+
comment.returns = comment.getTag("returns")!.text;
298+
comment.removeTags("returns");
299+
}
291300

292-
childComment.shortText =
293-
childComment.shortText || comment.shortText;
294-
childComment.text = childComment.text || comment.text;
295-
childComment.returns =
296-
childComment.returns || comment.returns;
297-
childComment.tags = childComment.tags || comment.tags;
298-
}
301+
signatures.forEach((signature) => {
302+
let childComment = signature.comment;
303+
if (childComment && childComment.hasTag("returns")) {
304+
childComment.returns = childComment.getTag("returns")!.text;
305+
childComment.removeTags("returns");
306+
}
299307

300-
if (signature.parameters) {
301-
signature.parameters.forEach((parameter) => {
302-
let tag: CommentTag | undefined;
303-
if (childComment) {
304-
tag = childComment.getTag("param", parameter.name);
305-
}
306-
if (comment && !tag) {
307-
tag = comment.getTag("param", parameter.name);
308-
}
309-
if (tag) {
310-
parameter.comment = new Comment(tag.text);
311-
}
312-
});
308+
if (comment) {
309+
if (!childComment) {
310+
movedComment = true;
311+
childComment = signature.comment = new Comment();
313312
}
314313

315-
childComment?.removeTags("param");
316-
});
314+
childComment.shortText =
315+
childComment.shortText || comment.shortText;
316+
childComment.text = childComment.text || comment.text;
317+
childComment.returns = childComment.returns || comment.returns;
318+
childComment.tags = childComment.tags || comment.tags;
319+
}
317320

318-
comment?.removeTags("param");
319-
}
321+
if (signature.parameters) {
322+
signature.parameters.forEach((parameter) => {
323+
let tag: CommentTag | undefined;
324+
if (childComment) {
325+
tag = childComment.getTag("param", parameter.name);
326+
}
327+
if (comment && !tag) {
328+
tag = comment.getTag("param", parameter.name);
329+
}
330+
if (tag) {
331+
parameter.comment = new Comment(tag.text);
332+
}
333+
});
334+
}
335+
336+
childComment?.removeTags("param");
337+
});
338+
339+
comment?.removeTags("param");
340+
if (movedComment) reflection.comment = void 0;
320341
}
321342

322343
private removeExcludedTags(comment: Comment) {

‎src/lib/models/reflections/declaration.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,15 @@ export class DeclarationReflection
161161
return result;
162162
}
163163

164+
/** @internal */
165+
getNonIndexSignatures(): SignatureReflection[] {
166+
return ([] as SignatureReflection[]).concat(
167+
this.signatures ?? [],
168+
this.setSignature ?? [],
169+
this.getSignature ?? []
170+
);
171+
}
172+
164173
/**
165174
* Traverse all potential child reflections of this reflection.
166175
*

‎src/test/converter/alias/specs.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,6 @@
9393
"kind": 4194304,
9494
"kindString": "Type alias",
9595
"flags": {},
96-
"comment": {
97-
"shortText": "A type that describes a compare function, e.g. for array.sort()."
98-
},
9996
"typeParameter": [
10097
{
10198
"id": 6,
@@ -120,6 +117,9 @@
120117
"kind": 4096,
121118
"kindString": "Call signature",
122119
"flags": {},
120+
"comment": {
121+
"shortText": "A type that describes a compare function, e.g. for array.sort()."
122+
},
123123
"parameters": [
124124
{
125125
"id": 4,

‎src/test/converter/mixin/specs.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -831,9 +831,6 @@
831831
"kind": 4194304,
832832
"kindString": "Type alias",
833833
"flags": {},
834-
"comment": {
835-
"shortText": "Any constructor function"
836-
},
837834
"typeParameter": [
838835
{
839836
"id": 10,
@@ -862,6 +859,9 @@
862859
"kind": 16384,
863860
"kindString": "Constructor signature",
864861
"flags": {},
862+
"comment": {
863+
"shortText": "Any constructor function"
864+
},
865865
"parameters": [
866866
{
867867
"id": 9,
@@ -895,9 +895,6 @@
895895
"kind": 4194304,
896896
"kindString": "Type alias",
897897
"flags": {},
898-
"comment": {
899-
"shortText": "Any function"
900-
},
901898
"typeParameter": [
902899
{
903900
"id": 5,
@@ -926,6 +923,9 @@
926923
"kind": 4096,
927924
"kindString": "Call signature",
928925
"flags": {},
926+
"comment": {
927+
"shortText": "Any function"
928+
},
929929
"parameters": [
930930
{
931931
"id": 4,

‎src/test/renderer/specs/classes/flattened.flattenedclass.html‎

Lines changed: 10 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -171,19 +171,6 @@ <h3>callback</h3>
171171
<div class="tsd-signature tsd-kind-icon">callback<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span>param<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">number</span>, optionalParam<span class="tsd-signature-symbol">?: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> =&gt; </span><span class="tsd-signature-type">string</span></div>
172172
<aside class="tsd-sources">
173173
</aside>
174-
<div class="tsd-comment tsd-typography">
175-
<div class="lead">
176-
<p>A member that holds a callback that requires a typed function signature.</p>
177-
</div>
178-
<dl class="tsd-comment-tags">
179-
<dt>param</dt>
180-
<dd><p>A parameter of the typed function callback.</p>
181-
</dd>
182-
<dt>param</dt>
183-
<dd><p>An optional parameter of the typed function callback.</p>
184-
</dd>
185-
</dl>
186-
</div>
187174
<div class="tsd-type-declaration">
188175
<h4>Type declaration</h4>
189176
<ul class="tsd-parameters">
@@ -193,6 +180,11 @@ <h4>Type declaration</h4>
193180
</ul>
194181
<ul class="tsd-descriptions">
195182
<li class="tsd-description">
183+
<div class="tsd-comment tsd-typography">
184+
<div class="lead">
185+
<p>A member that holds a callback that requires a typed function signature.</p>
186+
</div>
187+
</div>
196188
<h4 class="tsd-parameters-title">Parameters</h4>
197189
<ul class="tsd-parameters">
198190
<li>
@@ -364,11 +356,6 @@ <h3>single<wbr>Call<wbr>Signature</h3>
364356
<div class="tsd-signature tsd-kind-icon">single<wbr>Call<wbr>Signature<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-signature-symbol">...</span>args<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> =&gt; </span><span class="tsd-signature-symbol">(</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> =&gt; </span><span class="tsd-signature-type">string</span></div>
365357
<aside class="tsd-sources">
366358
</aside>
367-
<div class="tsd-comment tsd-typography">
368-
<div class="lead">
369-
<p>Single call signature.</p>
370-
</div>
371-
</div>
372359
<div class="tsd-type-declaration">
373360
<h4>Type declaration</h4>
374361
<ul class="tsd-parameters">
@@ -378,6 +365,11 @@ <h4>Type declaration</h4>
378365
</ul>
379366
<ul class="tsd-descriptions">
380367
<li class="tsd-description">
368+
<div class="tsd-comment tsd-typography">
369+
<div class="lead">
370+
<p>Single call signature.</p>
371+
</div>
372+
</div>
381373
<h4 class="tsd-parameters-title">Parameters</h4>
382374
<ul class="tsd-parameters">
383375
<li>

‎src/test/renderer/specs/modules/mixin.html‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -111,11 +111,6 @@ <h3>Any<wbr>Constructor</h3>
111111
<div class="tsd-signature tsd-kind-icon">Any<wbr>Constructor&lt;A&gt;<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">new </span><span class="tsd-signature-symbol">(</span><span class="tsd-signature-symbol">...</span>input<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> =&gt; </span><span class="tsd-signature-type">A</span></div>
112112
<aside class="tsd-sources">
113113
</aside>
114-
<div class="tsd-comment tsd-typography">
115-
<div class="lead">
116-
<p>Any constructor function</p>
117-
</div>
118-
</div>
119114
<h4 class="tsd-type-parameters-title">Type parameters</h4>
120115
<ul class="tsd-type-parameters">
121116
<li>
@@ -131,6 +126,11 @@ <h4>Type declaration</h4>
131126
</ul>
132127
<ul class="tsd-descriptions">
133128
<li class="tsd-description">
129+
<div class="tsd-comment tsd-typography">
130+
<div class="lead">
131+
<p>Any constructor function</p>
132+
</div>
133+
</div>
134134
<h4 class="tsd-parameters-title">Parameters</h4>
135135
<ul class="tsd-parameters">
136136
<li>
@@ -150,11 +150,6 @@ <h3>Any<wbr>Function</h3>
150150
<div class="tsd-signature tsd-kind-icon">Any<wbr>Function&lt;A&gt;<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-signature-symbol">...</span>input<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">any</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol"> =&gt; </span><span class="tsd-signature-type">A</span></div>
151151
<aside class="tsd-sources">
152152
</aside>
153-
<div class="tsd-comment tsd-typography">
154-
<div class="lead">
155-
<p>Any function</p>
156-
</div>
157-
</div>
158153
<h4 class="tsd-type-parameters-title">Type parameters</h4>
159154
<ul class="tsd-type-parameters">
160155
<li>
@@ -170,6 +165,11 @@ <h4>Type declaration</h4>
170165
</ul>
171166
<ul class="tsd-descriptions">
172167
<li class="tsd-description">
168+
<div class="tsd-comment tsd-typography">
169+
<div class="lead">
170+
<p>Any function</p>
171+
</div>
172+
</div>
173173
<h4 class="tsd-parameters-title">Parameters</h4>
174174
<ul class="tsd-parameters">
175175
<li>

0 commit comments

Comments
 (0)