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.
aws · Apr 15, 2019 · ae85aa5 · ae85aa5
1 parent 4d84e0b
commit ae85aa5
Show file tree

Hide file tree

Showing 38 changed files with 476 additions and 190 deletions.
diff --git a/packages/jsii-calc/lib/compliance.ts b/packages/jsii-calc/lib/compliance.ts
@@ -1617,3 +1617,22 @@ export class OptionalStructConsumer {
 export interface OptionalStruct {
     readonly field?: string;
 }
+
+
+/**
+ * This class has docs.
+ *
+ * The docs are great. They're a bunch of tags.
+ *
+ * @example
+ *
+ * function anExample() {
+ * }
+ *
+ * @see https://aws.amazon.com/
+ * @customAttribute hasAValue
+ * @deprecated Use something else please
+ * @stable
+ */
+export class ClassWithDocs {
+}
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
@@ -1506,6 +1506,28 @@
         }
       ]
     },
+    "jsii-calc.ClassWithDocs": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "custom": {
+          "customAttribute": "hasAValue"
+        },
+        "deprecated": "Use something else please",
+        "example": "function anExample() {\n}",
+        "remarks": "The docs are great. They're a bunch of tags.",
+        "see": "https://aws.amazon.com/",
+        "stability": "stable",
+        "summary": "This class has docs."
+      },
+      "fqn": "jsii-calc.ClassWithDocs",
+      "initializer": {},
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 1637
+      },
+      "name": "ClassWithDocs"
+    },
     "jsii-calc.ClassWithMutableObjectLiteralProperty": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.ClassWithMutableObjectLiteralProperty",
@@ -6637,5 +6659,5 @@
     }
   },
   "version": "0.9.0",
-  "fingerprint": "Lg8wDjQSsRLa2sk8EriArt/u5aibYilCuYFRZHh02Eg="
+  "fingerprint": "F319lrdZvWrVwdgKTX3nSjnYs1YghHSnYqGopWs2N+0="
 }
diff --git a/...t-generator/src/Amazon.JSII.Generator.UnitTests/Class/AbstractClassProxyGeneratorTests.cs b/...t-generator/src/Amazon.JSII.Generator.UnitTests/Class/AbstractClassProxyGeneratorTests.cs
@@ -1,6 +1,7 @@
 using Amazon.JSII.Generator.Class;
 using Amazon.JSII.JsonModel.Spec;
 using Xunit;
+using System.Collections.Generic;
 
 namespace Amazon.JSII.Generator.UnitTests.Class
 {
@@ -58,7 +59,7 @@ public void IncludesDocs()
                 name: "myClass",
                 isAbstract: true,
                 initializer: new Initializer(),
-                docs: new Docs {{"foo", "bar"}}
+                docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
             );
 
             string actual = Render(classType);

diff --git a/...es/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassGeneratorTests.cs b/...es/jsii-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassGeneratorTests.cs
@@ -3,6 +3,7 @@
 using Microsoft.CodeAnalysis;
 using Xunit;
 using TypeKind = Amazon.JSII.JsonModel.Spec.TypeKind;
+using System.Collections.Generic;
 
 namespace Amazon.JSII.Generator.UnitTests.Class
 {
@@ -133,7 +134,7 @@ public void IncludesDocs()
                 name: "myClass",
                 isAbstract: false,
                 initializer: new Initializer(),
-                docs: new Docs {{"foo", "bar"}}
+                docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
             );
 
             string actual = Render(classType);

diff --git a/...i-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassMethodGeneratorTests.cs b/...i-dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassMethodGeneratorTests.cs
@@ -3,6 +3,7 @@
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Xunit;
+using System.Collections.Generic;
 
 namespace Amazon.JSII.Generator.UnitTests.Class
 {
@@ -114,7 +115,7 @@ public void DoesNotIncludeDocs()
             Method method = new Method
             (
                 name: "myMethod",
-                docs: new Docs { { "foo", "bar" } }
+                docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
             );
 
             Symbols.MapMethodName("myClassFqn", "myMethod", "MyMethod");

diff --git a/...dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassPropertyGeneratorTests.cs b/...dotnet-generator/src/Amazon.JSII.Generator.UnitTests/Class/ClassPropertyGeneratorTests.cs
@@ -3,6 +3,7 @@
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using Xunit;
+using System.Collections.Generic;
 
 namespace Amazon.JSII.Generator.UnitTests.Class
 {
@@ -198,7 +199,7 @@ public void DoesNotIncludeDocs()
                 isImmutable: true,
                 isAbstract: false,
                 isProtected: false,
-                docs: new Docs { { "foo", "bar" } }
+                docs: new Docs(custom: new Dictionary<string, string>{{"foo", "bar"}})
             );
 
             Symbols.MapPropertyName("myClassFqn", "myProperty", "MyProperty");

diff --git a/...ator/src/Amazon.JSII.Generator.UnitTests/DocComment/EnumMemberDocCommentGeneratorTests.cs b/...ator/src/Amazon.JSII.Generator.UnitTests/DocComment/EnumMemberDocCommentGeneratorTests.cs
@@ -3,6 +3,7 @@
 using Microsoft.CodeAnalysis;
 using Xunit;
 using SF = Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
+using System.Collections.Generic;
 
 namespace Amazon.JSII.Generator.UnitTests.DocComment
 {
@@ -29,9 +30,9 @@ string Render(Docs docs)
         public void IncludesSingleLineSummary()
         {
             Docs docs = new Docs
-            {
-                { "summary", "my comment" }
-            };
+            (
+                summary: "my comment"
+            );
 
             string actual = Render(docs);
             string expected =
@@ -47,9 +48,9 @@ public void IncludesSingleLineSummary()
         public void IncludesMultiLineSummary(string summary)
         {
             Docs docs = new Docs
-            {
-                { "summary", summary }
-            };
+            (
+                summary: summary
+            );
 
             string actual = Render(docs);
             string expected =
@@ -66,9 +67,9 @@ public void IncludesMultiLineSummary(string summary)
         public void IncludesSingleLineRemarks()
         {
             Docs docs = new Docs
-            {
-                { "myKey", "my comment" }
-            };
+            (
+                custom: new Dictionary<string, string>{{ "myKey", "my comment" }}
+            );
 
             string actual = Render(docs);
             string expected =
@@ -82,10 +83,12 @@ public void IncludesSingleLineRemarks()
         public void IncludesMultiLineRemarks()
         {
             Docs docs = new Docs
-            {
-                { "myKey1", "my\ncomment" },
-                { "myKey2", "my\r\ncomment" }
-            };
+            (
+                custom: new Dictionary<string, string>{
+                    { "myKey1", "my\ncomment" },
+                    { "myKey2", "my\r\ncomment" }
+                }
+            );
 
             string actual = Render(docs);
             string expected =
@@ -104,9 +107,9 @@ public void IncludesMultiLineRemarks()
         public void SeparatesSingleLineLink()
         {
             Docs docs = new Docs
-            {
-                { "link", "www.example.com" }
-            };
+            (
+                custom: new Dictionary<string, string>{{ "link", "www.example.com" }}
+            );
 
             string actual = Render(docs);
             string expected =
@@ -120,9 +123,9 @@ public void SeparatesSingleLineLink()
         public void IgnoresParam()
         {
             Docs docs = new Docs
-            {
-                { "param", "my comment" }
-            };
+            (
+                custom: new Dictionary<string, string>{{ "param", "my comment" }}
+            );
 
             string actual = Render(docs);
             string expected = @"Member";
@@ -134,9 +137,9 @@ public void IgnoresParam()
         public void IgnoresReturns()
         {
             Docs docs = new Docs
-            {
-                { "returns", "my comment" }
-            };
+            (
+                returns: "my comment"
+            );
 
             string actual = Render(docs);
             string expected = @"Member";

diff --git a/...enerator/src/Amazon.JSII.Generator.UnitTests/DocComment/MethodDocCommentGeneratorTests.cs b/...enerator/src/Amazon.JSII.Generator.UnitTests/DocComment/MethodDocCommentGeneratorTests.cs
@@ -3,6 +3,7 @@
 using Microsoft.CodeAnalysis;
 using Xunit;
 using SF = Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
+using System.Collections.Generic;
 
 namespace Amazon.JSII.Generator.UnitTests.DocComment
 {
@@ -34,9 +35,9 @@ string Render(Docs docs, params Parameter[] parameters)
         public void IncludesSingleLineSummary()
         {
             Docs docs = new Docs
-            {
-                { "summary", "my comment" }
-            };
+            (
+                summary: "my comment"
+            );
 
             string actual = Render(docs);
             string expected =
@@ -52,9 +53,9 @@ public void IncludesSingleLineSummary()
         public void IncludesMultiLineSummary(string summary)
         {
             Docs docs = new Docs
-            {
-                { "summary", summary }
-            };
+            (
+                summary: summary
+            );
 
             string actual = Render(docs);
             string expected =
@@ -71,9 +72,9 @@ public void IncludesMultiLineSummary(string summary)
         public void IncludesSingleLineRemarks()
         {
             Docs docs = new Docs
-            {
-                { "myKey", "my comment" }
-            };
+            (
+                custom: new Dictionary<string,  string>{{ "myKey", "my comment" }}
+            );
 
             string actual = Render(docs);
             string expected =
@@ -87,10 +88,12 @@ public void IncludesSingleLineRemarks()
         public void IncludesMultiLineRemarks()
         {
             Docs docs = new Docs
-            {
-                { "myKey1", "my\ncomment" },
-                { "myKey2", "my\r\ncomment" }
-            };
+            (
+                custom: new Dictionary<string, string>{
+                    { "myKey1", "my\ncomment" },
+                    { "myKey2", "my\r\ncomment" }
+                }
+            );
 
             string actual = Render(docs);
             string expected =
@@ -109,9 +112,9 @@ public void IncludesMultiLineRemarks()
         public void SeparatesSingleLineLink()
         {
             Docs docs = new Docs
-            {
-                { "link", "www.example.com" }
-            };
+            (
+                custom: new Dictionary<string, string>{ { "link", "www.example.com" } }
+            );
 
             string actual = Render(docs);
             string expected =
@@ -125,9 +128,9 @@ public void SeparatesSingleLineLink()
         public void IgnoresParam()
         {
             Docs docs = new Docs
-            {
-                { "param", "my comment" }
-            };
+            (
+                custom: new Dictionary<string, string>{ { "param", "my comment" } }
+            );
 
             string actual = Render(docs);
             string expected = @"void Method()";
@@ -139,9 +142,9 @@ public void IgnoresParam()
         public void IncludesReturns()
         {
             Docs docs = new Docs
-            {
-                { "returns", "my comment" }
-            };
+            (
+                returns: "my comment"
+            );
 
             string actual = Render(docs);
             string expected =
@@ -158,9 +161,9 @@ public void IgnoresParameterParam()
                 name: "myParam",
                 type: new TypeReference(primitive: PrimitiveType.String),
                 docs: new Docs
-                {
-                    { "param", "my comment" }
-                }
+                (
+                    custom: new Dictionary<string, string>{ { "param", "my comment" } }
+                )
             );
 
             Symbols.MapParameterName("myParam", "myParam");
@@ -178,9 +181,9 @@ public void TrimsParameterSummary()
                 name: "myParam",
                 type: new TypeReference(primitive: PrimitiveType.String),
                 docs: new Docs
-                {
-                    { "summary", "my comment" }
-                }
+                (
+                    summary: "my comment"
+                )
             );
 
             Symbols.MapParameterName("myParam", "myParam");
@@ -193,27 +196,23 @@ public void TrimsParameterSummary()
             Assert.Equal(expected, actual, ignoreLineEndingDifferences: true);
         }
 
-        [Fact(DisplayName = Prefix + nameof(IncludesParameterRemarks))]
-        public void IncludesParameterRemarks()
+        [Fact(DisplayName = Prefix + nameof(IncludesParameterSummary))]
+        public void IncludesParameterSummary()
         {
             Parameter parameter = new Parameter(
                 name: "myParam",
                 type: new TypeReference(primitive: PrimitiveType.String),
                 docs: new Docs
-                {
-                    { "myKey1", "my comment" },
-                    { "myKey2", "my comment" }
-                }
+                (
+                    summary: "This parameter is swell"
+                )
             );
 
             Symbols.MapParameterName("myParam", "myParam");
 
             string actual = Render(null, parameter);
             string expected =
-@"/// <param name = ""myParam"">
-/// myKey1: my comment
-/// myKey2: my comment
-/// </param>
+@"/// <param name = ""myParam"">This parameter is swell</param>
         void Method()";
 
             Assert.Equal(expected, actual, ignoreLineEndingDifferences: true);