Skip to content

Commit

Permalink
fix: Correctly handle comments on function type aliases
Browse files Browse the repository at this point in the history 
Resolves #799.
  • Loading branch information
@Gerrit0
Gerrit0 committed Jun 15, 2021
1 parent 1dc5659 commit 1b1cd14
Show file tree
Hide file tree
Showing 6 changed files with 101 additions and 79 deletions.
105 changes: 63 additions & 42 deletions src/lib/converter/plugins/CommentPlugin.ts
View file
Expand Up @@ -7,6 +7,7 @@ import {
ReflectionKind,
TypeParameterReflection,
DeclarationReflection,
SignatureReflection,
} from "../../models/reflections/index";
import { Component, ConverterComponent } from "../components";
import {
Expand All @@ -17,7 +18,7 @@ import {
import { Converter } from "../converter";
import { Context } from "../context";
import { partition, uniq } from "lodash";
import { SourceReference } from "../../models";
import { ReflectionType, SourceReference } from "../../models";
import { BindOption, filterMap, removeIfPresent } from "../../utils";

/**
Expand Down Expand Up @@ -269,54 +270,74 @@ export class CommentPlugin extends ConverterComponent {
return;
}

const signatures = reflection.getAllSignatures();
if (signatures.length) {
const comment = reflection.comment;
if (comment && comment.hasTag("returns")) {
comment.returns = comment.getTag("returns")!.text;
comment.removeTags("returns");
}
if (reflection.type instanceof ReflectionType) {
this.addCommentToSignatures(
reflection,
reflection.type.declaration.getNonIndexSignatures()
);
} else {
this.addCommentToSignatures(
reflection,
reflection.getNonIndexSignatures()
);
}
}

signatures.forEach((signature) => {
let childComment = signature.comment;
if (childComment && childComment.hasTag("returns")) {
childComment.returns = childComment.getTag("returns")!.text;
childComment.removeTags("returns");
}
private addCommentToSignatures(
reflection: DeclarationReflection,
signatures: SignatureReflection[]
) {
if (!signatures.length) {
return;
}

if (comment) {
if (!childComment) {
childComment = signature.comment = new Comment();
}
let movedComment = false;
const comment = reflection.comment;
if (comment && comment.hasTag("returns")) {
comment.returns = comment.getTag("returns")!.text;
comment.removeTags("returns");
}

childComment.shortText =
childComment.shortText || comment.shortText;
childComment.text = childComment.text || comment.text;
childComment.returns =
childComment.returns || comment.returns;
childComment.tags = childComment.tags || comment.tags;
}
signatures.forEach((signature) => {
let childComment = signature.comment;
if (childComment && childComment.hasTag("returns")) {
childComment.returns = childComment.getTag("returns")!.text;
childComment.removeTags("returns");
}

if (signature.parameters) {
signature.parameters.forEach((parameter) => {
let tag: CommentTag | undefined;
if (childComment) {
tag = childComment.getTag("param", parameter.name);
}
if (comment && !tag) {
tag = comment.getTag("param", parameter.name);
}
if (tag) {
parameter.comment = new Comment(tag.text);
}
});
if (comment) {
if (!childComment) {
movedComment = true;
childComment = signature.comment = new Comment();
}

childComment?.removeTags("param");
});
childComment.shortText =
childComment.shortText || comment.shortText;
childComment.text = childComment.text || comment.text;
childComment.returns = childComment.returns || comment.returns;
childComment.tags = childComment.tags || comment.tags;
}

comment?.removeTags("param");
}
if (signature.parameters) {
signature.parameters.forEach((parameter) => {
let tag: CommentTag | undefined;
if (childComment) {
tag = childComment.getTag("param", parameter.name);
}
if (comment && !tag) {
tag = comment.getTag("param", parameter.name);
}
if (tag) {
parameter.comment = new Comment(tag.text);
}
});
}

childComment?.removeTags("param");
});

comment?.removeTags("param");
if (movedComment) reflection.comment = void 0;
}

private removeExcludedTags(comment: Comment) {
Expand Down
9 changes: 9 additions & 0 deletions src/lib/models/reflections/declaration.ts
View file
Expand Up @@ -161,6 +161,15 @@ export class DeclarationReflection
return result;
}

/** @internal */
getNonIndexSignatures(): SignatureReflection[] {
return ([] as SignatureReflection[]).concat(
this.signatures ?? [],
this.setSignature ?? [],
this.getSignature ?? []
);
}

/**
* Traverse all potential child reflections of this reflection.
*
Expand Down
6 changes: 3 additions & 3 deletions src/test/converter/alias/specs.json
View file
Expand Up @@ -93,9 +93,6 @@
"kind": 4194304,
"kindString": "Type alias",
"flags": {},
"comment": {
"shortText": "A type that describes a compare function, e.g. for array.sort()."
},
"typeParameter": [
{
"id": 6,
Expand All @@ -120,6 +117,9 @@
"kind": 4096,
"kindString": "Call signature",
"flags": {},
"comment": {
"shortText": "A type that describes a compare function, e.g. for array.sort()."
},
"parameters": [
{
"id": 4,
Expand Down
12 changes: 6 additions & 6 deletions src/test/converter/mixin/specs.json
View file
Expand Up @@ -831,9 +831,6 @@
"kind": 4194304,
"kindString": "Type alias",
"flags": {},
"comment": {
"shortText": "Any constructor function"
},
"typeParameter": [
{
"id": 10,
Expand Down Expand Up @@ -862,6 +859,9 @@
"kind": 16384,
"kindString": "Constructor signature",
"flags": {},
"comment": {
"shortText": "Any constructor function"
},
"parameters": [
{
"id": 9,
Expand Down Expand Up @@ -895,9 +895,6 @@
"kind": 4194304,
"kindString": "Type alias",
"flags": {},
"comment": {
"shortText": "Any function"
},
"typeParameter": [
{
"id": 5,
Expand Down Expand Up @@ -926,6 +923,9 @@
"kind": 4096,
"kindString": "Call signature",
"flags": {},
"comment": {
"shortText": "Any function"
},
"parameters": [
{
"id": 4,
Expand Down
28 changes: 10 additions & 18 deletions src/test/renderer/specs/classes/flattened.flattenedclass.html
View file
Expand Up @@ -171,19 +171,6 @@ <h3>callback</h3>
<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>
<aside class="tsd-sources">
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>A member that holds a callback that requires a typed function signature.</p>
</div>
<dl class="tsd-comment-tags">
<dt>param</dt>
<dd><p>A parameter of the typed function callback.</p>
</dd>
<dt>param</dt>
<dd><p>An optional parameter of the typed function callback.</p>
</dd>
</dl>
</div>
<div class="tsd-type-declaration">
<h4>Type declaration</h4>
<ul class="tsd-parameters">
Expand All @@ -193,6 +180,11 @@ <h4>Type declaration</h4>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>A member that holds a callback that requires a typed function signature.</p>
</div>
</div>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
Expand Down Expand Up @@ -364,11 +356,6 @@ <h3>single<wbr>Call<wbr>Signature</h3>
<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>
<aside class="tsd-sources">
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Single call signature.</p>
</div>
</div>
<div class="tsd-type-declaration">
<h4>Type declaration</h4>
<ul class="tsd-parameters">
Expand All @@ -378,6 +365,11 @@ <h4>Type declaration</h4>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Single call signature.</p>
</div>
</div>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
Expand Down
20 changes: 10 additions & 10 deletions src/test/renderer/specs/modules/mixin.html
View file
Expand Up @@ -111,11 +111,6 @@ <h3>Any<wbr>Constructor</h3>
<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>
<aside class="tsd-sources">
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Any constructor function</p>
</div>
</div>
<h4 class="tsd-type-parameters-title">Type parameters</h4>
<ul class="tsd-type-parameters">
<li>
Expand All @@ -131,6 +126,11 @@ <h4>Type declaration</h4>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Any constructor function</p>
</div>
</div>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
Expand All @@ -150,11 +150,6 @@ <h3>Any<wbr>Function</h3>
<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>
<aside class="tsd-sources">
</aside>
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Any function</p>
</div>
</div>
<h4 class="tsd-type-parameters-title">Type parameters</h4>
<ul class="tsd-type-parameters">
<li>
Expand All @@ -170,6 +165,11 @@ <h4>Type declaration</h4>
</ul>
<ul class="tsd-descriptions">
<li class="tsd-description">
<div class="tsd-comment tsd-typography">
<div class="lead">
<p>Any function</p>
</div>
</div>
<h4 class="tsd-parameters-title">Parameters</h4>
<ul class="tsd-parameters">
<li>
Expand Down

0 comments on commit 1b1cd14

Please sign in to comment.