Skip to content

Commit ae85aa5

Browse files
authored
fix(dotnet): fix doc comment model parsing in .NET generator (#455)
Mirror the changes to assembly docs model in the separate model that the .NET generator maintains. This fixes the crash that happens when parsing a model with custom doc attributes. Add compliance test to prevent this from happening again.
1 parent 4d84e0b commit ae85aa5

38 files changed

+476
-190
lines changed

packages/jsii-calc/lib/compliance.ts

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1617,3 +1617,22 @@ export class OptionalStructConsumer {
16171617
export interface OptionalStruct {
16181618
readonly field?: string;
16191619
}
1620+
1621+
1622+
/**
1623+
* This class has docs.
1624+
*
1625+
* The docs are great. They're a bunch of tags.
1626+
*
1627+
* @example
1628+
*
1629+
* function anExample() {
1630+
* }
1631+
*
1632+
* @see https://aws.amazon.com/
1633+
* @customAttribute hasAValue
1634+
* @deprecated Use something else please
1635+
* @stable
1636+
*/
1637+
export class ClassWithDocs {
1638+
}

packages/jsii-calc/test/assembly.jsii

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1506,6 +1506,28 @@
15061506
}
15071507
]
15081508
},
1509+
"jsii-calc.ClassWithDocs": {
1510+
"assembly": "jsii-calc",
1511+
"docs": {
1512+
"custom": {
1513+
"customAttribute": "hasAValue"
1514+
},
1515+
"deprecated": "Use something else please",
1516+
"example": "function anExample() {\n}",
1517+
"remarks": "The docs are great. They're a bunch of tags.",
1518+
"see": "https://aws.amazon.com/",
1519+
"stability": "stable",
1520+
"summary": "This class has docs."
1521+
},
1522+
"fqn": "jsii-calc.ClassWithDocs",
1523+
"initializer": {},
1524+
"kind": "class",
1525+
"locationInModule": {
1526+
"filename": "lib/compliance.ts",
1527+
"line": 1637
1528+
},
1529+
"name": "ClassWithDocs"
1530+
},
15091531
"jsii-calc.ClassWithMutableObjectLiteralProperty": {
15101532
"assembly": "jsii-calc",
15111533
"fqn": "jsii-calc.ClassWithMutableObjectLiteralProperty",
@@ -6637,5 +6659,5 @@
66376659
}
66386660
},
66396661
"version": "0.9.0",
6640-
"fingerprint": "Lg8wDjQSsRLa2sk8EriArt/u5aibYilCuYFRZHh02Eg="
6662+
"fingerprint": "F319lrdZvWrVwdgKTX3nSjnYs1YghHSnYqGopWs2N+0="
66416663
}

packages/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/AbstractClassProxyGeneratorTests.cs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
using Amazon.JSII.Generator.Class;
22
using Amazon.JSII.JsonModel.Spec;
33
using Xunit;
4+
using System.Collections.Generic;
45

56
namespace Amazon.JSII.Generator.UnitTests.Class
67
{
@@ -58,7 +59,7 @@ public void IncludesDocs()
5859
name: "myClass",
5960
isAbstract: true,
6061
initializer: new Initializer(),
61-
docs: new Docs {{"foo", "bar"}}
62+
docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
6263
);
6364

6465
string actual = Render(classType);

packages/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassGeneratorTests.cs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using Microsoft.CodeAnalysis;
44
using Xunit;
55
using TypeKind = Amazon.JSII.JsonModel.Spec.TypeKind;
6+
using System.Collections.Generic;
67

78
namespace Amazon.JSII.Generator.UnitTests.Class
89
{
@@ -133,7 +134,7 @@ public void IncludesDocs()
133134
name: "myClass",
134135
isAbstract: false,
135136
initializer: new Initializer(),
136-
docs: new Docs {{"foo", "bar"}}
137+
docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
137138
);
138139

139140
string actual = Render(classType);

packages/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassMethodGeneratorTests.cs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using Microsoft.CodeAnalysis;
44
using Microsoft.CodeAnalysis.CSharp.Syntax;
55
using Xunit;
6+
using System.Collections.Generic;
67

78
namespace Amazon.JSII.Generator.UnitTests.Class
89
{
@@ -114,7 +115,7 @@ public void DoesNotIncludeDocs()
114115
Method method = new Method
115116
(
116117
name: "myMethod",
117-
docs: new Docs { { "foo", "bar" } }
118+
docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
118119
);
119120

120121
Symbols.MapMethodName("myClassFqn", "myMethod", "MyMethod");

packages/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassPropertyGeneratorTests.cs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using Microsoft.CodeAnalysis;
44
using Microsoft.CodeAnalysis.CSharp.Syntax;
55
using Xunit;
6+
using System.Collections.Generic;
67

78
namespace Amazon.JSII.Generator.UnitTests.Class
89
{
@@ -198,7 +199,7 @@ public void DoesNotIncludeDocs()
198199
isImmutable: true,
199200
isAbstract: false,
200201
isProtected: false,
201-
docs: new Docs { { "foo", "bar" } }
202+
docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
202203
);
203204

204205
Symbols.MapPropertyName("myClassFqn", "myProperty", "MyProperty");

packages/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/DocComment/EnumMemberDocCommentGeneratorTests.cs

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using Microsoft.CodeAnalysis;
44
using Xunit;
55
using SF = Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
6+
using System.Collections.Generic;
67

78
namespace Amazon.JSII.Generator.UnitTests.DocComment
89
{
@@ -29,9 +30,9 @@ string Render(Docs docs)
2930
public void IncludesSingleLineSummary()
3031
{
3132
Docs docs = new Docs
32-
{
33-
{ "summary", "my comment" }
34-
};
33+
(
34+
summary: "my comment"
35+
);
3536

3637
string actual = Render(docs);
3738
string expected =
@@ -47,9 +48,9 @@ public void IncludesSingleLineSummary()
4748
public void IncludesMultiLineSummary(string summary)
4849
{
4950
Docs docs = new Docs
50-
{
51-
{ "summary", summary }
52-
};
51+
(
52+
summary: summary
53+
);
5354

5455
string actual = Render(docs);
5556
string expected =
@@ -66,9 +67,9 @@ public void IncludesMultiLineSummary(string summary)
6667
public void IncludesSingleLineRemarks()
6768
{
6869
Docs docs = new Docs
69-
{
70-
{ "myKey", "my comment" }
71-
};
70+
(
71+
custom: new Dictionary<string, string>{{ "myKey", "my comment" }}
72+
);
7273

7374
string actual = Render(docs);
7475
string expected =
@@ -82,10 +83,12 @@ public void IncludesSingleLineRemarks()
8283
public void IncludesMultiLineRemarks()
8384
{
8485
Docs docs = new Docs
85-
{
86-
{ "myKey1", "my\ncomment" },
87-
{ "myKey2", "my\r\ncomment" }
88-
};
86+
(
87+
custom: new Dictionary<string, string>{
88+
{ "myKey1", "my\ncomment" },
89+
{ "myKey2", "my\r\ncomment" }
90+
}
91+
);
8992

9093
string actual = Render(docs);
9194
string expected =
@@ -104,9 +107,9 @@ public void IncludesMultiLineRemarks()
104107
public void SeparatesSingleLineLink()
105108
{
106109
Docs docs = new Docs
107-
{
108-
{ "link", "www.example.com" }
109-
};
110+
(
111+
custom: new Dictionary<string, string>{{ "link", "www.example.com" }}
112+
);
110113

111114
string actual = Render(docs);
112115
string expected =
@@ -120,9 +123,9 @@ public void SeparatesSingleLineLink()
120123
public void IgnoresParam()
121124
{
122125
Docs docs = new Docs
123-
{
124-
{ "param", "my comment" }
125-
};
126+
(
127+
custom: new Dictionary<string, string>{{ "param", "my comment" }}
128+
);
126129

127130
string actual = Render(docs);
128131
string expected = @"Member";
@@ -134,9 +137,9 @@ public void IgnoresParam()
134137
public void IgnoresReturns()
135138
{
136139
Docs docs = new Docs
137-
{
138-
{ "returns", "my comment" }
139-
};
140+
(
141+
returns: "my comment"
142+
);
140143

141144
string actual = Render(docs);
142145
string expected = @"Member";

packages/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/DocComment/MethodDocCommentGeneratorTests.cs

Lines changed: 37 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using Microsoft.CodeAnalysis;
44
using Xunit;
55
using SF = Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
6+
using System.Collections.Generic;
67

78
namespace Amazon.JSII.Generator.UnitTests.DocComment
89
{
@@ -34,9 +35,9 @@ string Render(Docs docs, params Parameter[] parameters)
3435
public void IncludesSingleLineSummary()
3536
{
3637
Docs docs = new Docs
37-
{
38-
{ "summary", "my comment" }
39-
};
38+
(
39+
summary: "my comment"
40+
);
4041

4142
string actual = Render(docs);
4243
string expected =
@@ -52,9 +53,9 @@ public void IncludesSingleLineSummary()
5253
public void IncludesMultiLineSummary(string summary)
5354
{
5455
Docs docs = new Docs
55-
{
56-
{ "summary", summary }
57-
};
56+
(
57+
summary: summary
58+
);
5859

5960
string actual = Render(docs);
6061
string expected =
@@ -71,9 +72,9 @@ public void IncludesMultiLineSummary(string summary)
7172
public void IncludesSingleLineRemarks()
7273
{
7374
Docs docs = new Docs
74-
{
75-
{ "myKey", "my comment" }
76-
};
75+
(
76+
custom: new Dictionary<string, string>{{ "myKey", "my comment" }}
77+
);
7778

7879
string actual = Render(docs);
7980
string expected =
@@ -87,10 +88,12 @@ public void IncludesSingleLineRemarks()
8788
public void IncludesMultiLineRemarks()
8889
{
8990
Docs docs = new Docs
90-
{
91-
{ "myKey1", "my\ncomment" },
92-
{ "myKey2", "my\r\ncomment" }
93-
};
91+
(
92+
custom: new Dictionary<string, string>{
93+
{ "myKey1", "my\ncomment" },
94+
{ "myKey2", "my\r\ncomment" }
95+
}
96+
);
9497

9598
string actual = Render(docs);
9699
string expected =
@@ -109,9 +112,9 @@ public void IncludesMultiLineRemarks()
109112
public void SeparatesSingleLineLink()
110113
{
111114
Docs docs = new Docs
112-
{
113-
{ "link", "www.example.com" }
114-
};
115+
(
116+
custom: new Dictionary<string, string>{ { "link", "www.example.com" } }
117+
);
115118

116119
string actual = Render(docs);
117120
string expected =
@@ -125,9 +128,9 @@ public void SeparatesSingleLineLink()
125128
public void IgnoresParam()
126129
{
127130
Docs docs = new Docs
128-
{
129-
{ "param", "my comment" }
130-
};
131+
(
132+
custom: new Dictionary<string, string>{ { "param", "my comment" } }
133+
);
131134

132135
string actual = Render(docs);
133136
string expected = @"void Method()";
@@ -139,9 +142,9 @@ public void IgnoresParam()
139142
public void IncludesReturns()
140143
{
141144
Docs docs = new Docs
142-
{
143-
{ "returns", "my comment" }
144-
};
145+
(
146+
returns: "my comment"
147+
);
145148

146149
string actual = Render(docs);
147150
string expected =
@@ -158,9 +161,9 @@ public void IgnoresParameterParam()
158161
name: "myParam",
159162
type: new TypeReference(primitive: PrimitiveType.String),
160163
docs: new Docs
161-
{
162-
{ "param", "my comment" }
163-
}
164+
(
165+
custom: new Dictionary<string, string>{ { "param", "my comment" } }
166+
)
164167
);
165168

166169
Symbols.MapParameterName("myParam", "myParam");
@@ -178,9 +181,9 @@ public void TrimsParameterSummary()
178181
name: "myParam",
179182
type: new TypeReference(primitive: PrimitiveType.String),
180183
docs: new Docs
181-
{
182-
{ "summary", "my comment" }
183-
}
184+
(
185+
summary: "my comment"
186+
)
184187
);
185188

186189
Symbols.MapParameterName("myParam", "myParam");
@@ -193,27 +196,23 @@ public void TrimsParameterSummary()
193196
Assert.Equal(expected, actual, ignoreLineEndingDifferences: true);
194197
}
195198

196-
[Fact(DisplayName = Prefix + nameof(IncludesParameterRemarks))]
197-
public void IncludesParameterRemarks()
199+
[Fact(DisplayName = Prefix + nameof(IncludesParameterSummary))]
200+
public void IncludesParameterSummary()
198201
{
199202
Parameter parameter = new Parameter(
200203
name: "myParam",
201204
type: new TypeReference(primitive: PrimitiveType.String),
202205
docs: new Docs
203-
{
204-
{ "myKey1", "my comment" },
205-
{ "myKey2", "my comment" }
206-
}
206+
(
207+
summary: "This parameter is swell"
208+
)
207209
);
208210

209211
Symbols.MapParameterName("myParam", "myParam");
210212

211213
string actual = Render(null, parameter);
212214
string expected =
213-
@"/// <param name = ""myParam"">
214-
/// myKey1: my comment
215-
/// myKey2: my comment
216-
/// </param>
215+
@"/// <param name = ""myParam"">This parameter is swell</param>
217216
void Method()";
218217

219218
Assert.Equal(expected, actual, ignoreLineEndingDifferences: true);

0 commit comments

Comments
 (0)