Document comments

entity-framework/core/modeling/entity-properties.md

@@ -160,3 +160,20 @@ A collation can be defined on text columns, determining how they are compared an
 If all columns in a database need to use a certain collation, define the collation at the database level instead.
 
 General information about EF Core support for collations can be found in the [collation documentation page](xref:core/miscellaneous/collations-and-case-sensitivity).
+
+## Column comments
+
+You can set an arbitrary text comment that gets set on the database column, allowing you to document your schema in the database:
+
+### [Data Annotations](#tab/data-annotations)
+
+> [!NOTE]
+> Setting comments via data annotations was introduced in EF Core 5.0.
+
+[!code-csharp[Main](../../../samples/core/Modeling/DataAnnotations/ColumnComment.cs?name=ColumnComment&highlight=4)]
+
+### [Fluent API](#tab/fluent-api)
+
+[!code-csharp[Main](../../../samples/core/Modeling/FluentAPI/ColumnComment.cs?name=ColumnComment&highlight=5)]
+
+***

entity-framework/core/modeling/entity-types.md

@@ -99,3 +99,20 @@ Entity types can be mapped to database views using the Fluent API.
 
 > [!TIP]
 > To test entity types mapped to views using the in-memory provider map them to a query via `ToInMemoryQuery`. See a [runnable sample](https://github.com/dotnet/EntityFramework.Docs/tree/master/samples/core/Miscellaneous/Testing/ItemsWebApi/) using this technique for more details.
+
+## Table comments
+
+You can set an arbitrary text comment that gets set on the database table, allowing you to document your schema in the database:
+
+### [Data Annotations](#tab/data-annotations)
+
+> [!NOTE]
+> Setting comments via data annotations was introduced in EF Core 5.0.
+
+[!code-csharp[Main](../../../samples/core/Modeling/DataAnnotations/TableComment.cs?name=TableComment&highlight=1)]
+
+### [Fluent API](#tab/fluent-api)
+
+[!code-csharp[Main](../../../samples/core/Modeling/FluentAPI/TableComment.cs?name=TableComment&highlight=4)]
+
+***

samples/core/Modeling/DataAnnotations/ColumnComment.cs

@@ -0,0 +1,19 @@
+using Microsoft.EntityFrameworkCore;
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace EFModeling.DataAnnotations.Relational.ColumnComment
+{
+    class MyContext : DbContext
+    {
+        public DbSet<Blog> Blogs { get; set; }
+    }
+
+    #region ColumnComment
+    public class Blog
+    {
+        public int BlogId { get; set; }
+        [Comment("The URL of the blog")]
+        public string Url { get; set; }
+    }
+    #endregion
+}

samples/core/Modeling/DataAnnotations/TableComment.cs

@@ -0,0 +1,19 @@
+using Microsoft.EntityFrameworkCore;
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace EFModeling.DataAnnotations.Relational.TableComment
+{
+    class MyContext : DbContext
+    {
+        public DbSet<Blog> Blogs { get; set; }
+    }
+
+    #region TableComment
+    [Comment("Blogs managed on the website")]
+    public class Blog
+    {
+        public int BlogId { get; set; }
+        public string Url { get; set; }
+    }
+    #endregion
+}

samples/core/Modeling/FluentAPI/ColumnComment.cs

@@ -0,0 +1,25 @@
+using Microsoft.EntityFrameworkCore;
+using System;
+
+namespace EFModeling.FluentAPI.ColumnComment
+{
+    class MyContext : DbContext
+    {
+        public DbSet<Blog> Blogs { get; set; }
+
+        #region ColumnComment
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<Blog>()
+                .Property(b => b.Url)
+                .HasComment("The URL of the blog");
+        }
+        #endregion
+    }
+
+    public class Blog
+    {
+        public int BlogId { get; set; }
+        public string Url { get; set; }
+    }
+}

samples/core/Modeling/FluentAPI/TableComment.cs

@@ -0,0 +1,24 @@
+using Microsoft.EntityFrameworkCore;
+using System;
+
+namespace EFModeling.FluentAPI.TableComment
+{
+    class MyContext : DbContext
+    {
+        public DbSet<Blog> Blogs { get; set; }
+
+        #region TableComment
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<Blog>()
+                .HasComment("Blogs managed on the website");
+        }
+        #endregion
+    }
+
+    public class Blog
+    {
+        public int BlogId { get; set; }
+        public string Url { get; set; }
+    }
+}