Add <inheritdoc /> in migrations

Closes dotnet#10695
roji · Jan 24, 2022 · 70e4b7f · 70e4b7f
1 parent 535ecd5
commit 70e4b7f
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 9 deletions.
diff --git a/src/EFCore.Design/Migrations/Design/CSharpMigrationsGenerator.cs b/src/EFCore.Design/Migrations/Design/CSharpMigrationsGenerator.cs
@@ -88,11 +88,13 @@ public override string GenerateMigration(
         }
 
         builder
+            .AppendLine("/// <inheritdoc />")
             .Append("public partial class ").Append(Code.Identifier(migrationName)).AppendLine(" : Migration")
             .AppendLine("{");
         using (builder.Indent())
         {
             builder
+                .AppendLine("/// <inheritdoc />")
                 .AppendLine("protected override void Up(MigrationBuilder migrationBuilder)")
                 .AppendLine("{");
             using (builder.Indent())
@@ -104,6 +106,7 @@ public override string GenerateMigration(
                 .AppendLine()
                 .AppendLine("}")
                 .AppendLine()
+                .AppendLine("/// <inheritdoc />")
                 .AppendLine("protected override void Down(MigrationBuilder migrationBuilder)")
                 .AppendLine("{");
             using (builder.Indent())
@@ -191,6 +194,7 @@ public override string GenerateMetadata(
         using (builder.Indent())
         {
             builder
+                .AppendLine("/// <inheritdoc />")
                 .AppendLine("protected override void BuildTargetModel(ModelBuilder modelBuilder)")
                 .AppendLine("{")
                 .DecrementIndent()

diff --git a/test/EFCore.Design.Tests/Migrations/Design/CSharpMigrationsGeneratorTest.cs b/test/EFCore.Design.Tests/Migrations/Design/CSharpMigrationsGeneratorTest.cs
@@ -499,8 +499,10 @@ public void Migrations_compile()
 
 namespace MyNamespace
 {
+    /// <inheritdoc />
     public partial class MyMigration : Migration
     {
+        /// <inheritdoc />
         protected override void Up(MigrationBuilder migrationBuilder)
         {
             migrationBuilder.Sql(""-- TEST"")
@@ -523,6 +525,7 @@ protected override void Up(MigrationBuilder migrationBuilder)
                 values: new object[] { 1, null, -1 });
         }
 
+        /// <inheritdoc />
         protected override void Down(MigrationBuilder migrationBuilder)
         {
 
@@ -571,6 +574,7 @@ namespace MyNamespace
     [Migration(""20150511161616_MyMigration"")]
     partial class MyMigration
     {
+        /// <inheritdoc />
         protected override void BuildTargetModel(ModelBuilder modelBuilder)
         {
 #pragma warning disable 612, 618
@@ -608,7 +612,8 @@ protected override void BuildTargetModel(ModelBuilder modelBuilder)
                 BuildReference.ByName("Microsoft.EntityFrameworkCore"),
                 BuildReference.ByName("Microsoft.EntityFrameworkCore.Relational")
             },
-            Sources = { { "Migration.cs", migrationCode }, { "MigrationSnapshot.cs", migrationMetadataCode } }
+            Sources = { { "Migration.cs", migrationCode }, { "MigrationSnapshot.cs", migrationMetadataCode } },
+            EmitDocumentationDiagnostics = true
         };
 
         var assembly = build.BuildInMemory();

diff --git a/test/EFCore.Relational.Specification.Tests/TestUtilities/BuildSource.cs b/test/EFCore.Relational.Specification.Tests/TestUtilities/BuildSource.cs
@@ -23,6 +23,7 @@ public class BuildSource
     public string TargetDir { get; set; }
     public Dictionary<string, string> Sources { get; set; } = new();
     public bool NullableReferenceTypes { get; set; }
+    public bool EmitDocumentationDiagnostics { get; set; }
 
     public BuildFileResult Build()
     {
@@ -46,7 +47,13 @@ public BuildFileResult Build()
 
         var compilation = CSharpCompilation.Create(
             projectName,
-            Sources.Select(s => SyntaxFactory.ParseSyntaxTree(s.Value).WithFilePath(s.Key)),
+            Sources.Select(
+                s => SyntaxFactory.ParseSyntaxTree(
+                    text: s.Value,
+                    path: s.Key,
+                    options: new CSharpParseOptions(
+                        LanguageVersion.Latest,
+                        EmitDocumentationDiagnostics ? DocumentationMode.Diagnose : DocumentationMode.Parse))),
             references,
             CreateOptions());
 
@@ -78,18 +85,40 @@ public Assembly BuildInMemory()
 
         var compilation = CSharpCompilation.Create(
             projectName,
-            Sources.Select(s => SyntaxFactory.ParseSyntaxTree(s.Value).WithFilePath(s.Key)),
+            Sources.Select(
+                s => SyntaxFactory.ParseSyntaxTree(
+                    text: s.Value,
+                    path: s.Key,
+                    options: new CSharpParseOptions(
+                        LanguageVersion.Latest,
+                        EmitDocumentationDiagnostics ? DocumentationMode.Diagnose : DocumentationMode.Parse))),
             references,
             CreateOptions());
 
+        var diagnostics = compilation.GetDiagnostics();
+        if (!diagnostics.IsEmpty)
+        {
+            throw new InvalidOperationException(
+                $@"Build failed.
+
+First diagnostic:
+{diagnostics[0]}
+
+Location:
+{diagnostics[0].Location.SourceTree?.GetRoot().FindNode(diagnostics[0].Location.SourceSpan)}
+
+All diagnostics:
+{string.Join(Environment.NewLine, diagnostics)}");
+        }
+
         Assembly assembly;
         using (var stream = new MemoryStream())
         {
             var result = compilation.Emit(stream);
             if (!result.Success)
             {
                 throw new InvalidOperationException(
-                    $@"Build failed:
+                    $@"Failed to emit compilation:
 {string.Join(Environment.NewLine, result.Diagnostics)}");
             }
 
@@ -107,12 +136,19 @@ private CSharpCompilationOptions CreateOptions()
             generalDiagnosticOption: ReportDiagnostic.Error,
             specificDiagnosticOptions: new Dictionary<string, ReportDiagnostic>
             {
+                // Displays the text of a warning defined with the #warning directive
                 { "CS1030", ReportDiagnostic.Suppress },
+
+                // Assuming assembly reference "Assembly Name #1" matches "Assembly Name #2", you may need to supply runtime policy
                 { "CS1701", ReportDiagnostic.Suppress },
-                { "CS1702", ReportDiagnostic.Suppress }, // Always thrown for .NET Core
-                {
-                    "CS1705", ReportDiagnostic.Suppress
-                }, // Assembly 'AssemblyName1' uses 'TypeName' which has a higher version than referenced assembly 'AssemblyName2'
-                { "CS8019", ReportDiagnostic.Suppress } // Unnecessary using directive.
+
+                // Assuming assembly reference "Assembly Name #1" matches "Assembly Name #2", you may need to supply runtime policy
+                { "CS1702", ReportDiagnostic.Suppress },
+
+                // Assembly 'AssemblyName1' uses 'TypeName' which has a higher version than referenced assembly 'AssemblyName2'
+                { "CS1705", ReportDiagnostic.Suppress },
+
+                // Unnecessary using directive.
+                { "CS8019", ReportDiagnostic.Suppress }
             });
 }