Added structural types and properties documentation properties

src/Microsoft.AspNet.OData.Shared/Builder/ActionOnDeleteAttribute.cs

@@ -6,7 +6,7 @@
 
 namespace Microsoft.AspNet.OData.Builder
 {
-    /// <summary>
+	/// <summary>
     /// Represents an <see cref="Attribute"/> that can be placed on a navigation property to specify the applied
     /// action whether delete should also remove the associated item on the other end of the association.
     /// </summary>

src/Microsoft.AspNet.OData.Shared/Builder/Conventions/ActionLinkGenerationConvention.cs

@@ -5,7 +5,7 @@
 
 namespace Microsoft.AspNet.OData.Builder.Conventions
 {
-    /// <summary>
+	/// <summary>
     /// The ActionLinkGenerationConvention calls action.HasActionLink(..) if the action binds to a single entity and has not previously been configured.
     /// </summary>
     internal class ActionLinkGenerationConvention : IOperationConvention

src/Microsoft.AspNet.OData.Shared/Builder/Conventions/Attributes/DescriptionAttribute.cs

@@ -0,0 +1,30 @@
+using System;
+
+namespace Microsoft.AspNet.OData.Builder.Conventions.Attributes
+{
+	/// <summary>
+	/// Represents an <see cref="Attribute"/> that can be placed on a property or class to document its purpose. The content will be includes in the Odata metadata document.
+	/// </summary>
+	[AttributeUsage(AttributeTargets.Property | AttributeTargets.Class, AllowMultiple = false, Inherited = false)]
+	public sealed class DescriptionAttribute : Attribute
+	{
+		/// <summary>
+		/// Gets or summary about the purpose of the property or class.
+		/// </summary>
+		public string Description { get; }
+
+		/// <summary>
+		/// Gets or sets a detailed description about the purpose of the property or class.
+		/// </summary>
+		public string LongDescription { get; set; }
+
+		/// <summary>
+		/// Initializes a new instance of the <see cref="DescriptionAttribute"/> class.
+		/// </summary>
+		/// <param name="description">A summary about the purpose of the property or class.</param>
+		public DescriptionAttribute(string description)
+		{
+			Description = description;
+		}
+	}
+}

src/Microsoft.AspNet.OData.Shared/Builder/Conventions/DescriptionAnnotationConvention.cs

@@ -0,0 +1,36 @@
+using System.Reflection;
+using Microsoft.AspNet.OData.Builder.Conventions.Attributes;
+
+namespace Microsoft.AspNet.OData.Builder.Conventions
+{
+	internal class DescriptionAnnotationConvention : IEdmTypeConvention
+	{
+		public void Apply(IEdmTypeConfiguration edmTypeConfiguration, ODataConventionModelBuilder model)
+		{
+			if (!(edmTypeConfiguration is StructuralTypeConfiguration structuralType)) return;
+
+			var attribute = (DescriptionAttribute) structuralType.ClrType.GetCustomAttribute(typeof(DescriptionAttribute), true);
+			if (attribute != null)
+			{
+				structuralType.Description = attribute.Description;
+				if (!string.IsNullOrEmpty(attribute.LongDescription))
+				{
+					structuralType.LongDescription = attribute.LongDescription;
+				}
+			}
+
+			foreach (var property in structuralType.Properties)
+			{
+				attribute = (DescriptionAttribute) property.PropertyInfo.GetCustomAttribute(typeof(DescriptionAttribute), true);
+				if (attribute != null)
+				{
+					property.Description = attribute.Description;
+					if (!string.IsNullOrEmpty(attribute.LongDescription))
+					{
+						property.LongDescription = attribute.LongDescription;
+					}
+				}
+			}
+		}
+	}
+}

src/Microsoft.AspNet.OData.Shared/Builder/EdmModelHelperMethods.cs

@@ -66,9 +66,46 @@ public static IEdmModel BuildEdmModel(ODataModelBuilder builder)
             // build the map from IEdmEntityType to IEdmFunctionImport
             model.SetAnnotationValue<BindableOperationFinder>(model, new BindableOperationFinder(model));
 
+            // Add annotations for documentation
+            AddDescriptionAnnotations(builder, model, edmTypeMap);
+
             return model;
         }
 
+        private static void AddDescriptionAnnotations(ODataModelBuilder builder, EdmModel model, IReadOnlyDictionary<Type, IEdmType> edmTypeMap)
+        {
+	        foreach (var structuralType in builder.StructuralTypes)
+	        {
+
+		        if (!edmTypeMap.TryGetValue(structuralType.ClrType, out var edmType)) continue;
+		        if (!(edmType is IEdmVocabularyAnnotatable target)) continue;
+
+		        if (!string.IsNullOrEmpty(structuralType.Description))
+		        {
+			        model.SetDescriptionAnnotation(target, structuralType.Description);
+		        }
+		        if (!string.IsNullOrEmpty(structuralType.LongDescription))
+		        {
+			        model.SetLongDescriptionAnnotation(target, structuralType.LongDescription);
+		        }
+
+		        if (edmType is IEdmStructuredType structuredType)
+		        {
+			        foreach (var entry in structuredType.DeclaredProperties.Join(structuralType.Properties, p => p.Name, p => p.Name, (property, configuration) => new {property, configuration}))
+			        {
+				        if (!string.IsNullOrEmpty(entry.configuration.Description))
+				        {
+					        model.SetDescriptionAnnotation(entry.property, entry.configuration.Description);
+				        } 
+				        if (!string.IsNullOrEmpty(entry.configuration.LongDescription))
+				        {
+					        model.SetLongDescriptionAnnotation(entry.property, entry.configuration.LongDescription);
+				        }
+			        }
+		        }
+	        }
+        }
+
         private static void AddTypes(this EdmModel model, Dictionary<Type, IEdmType> types)
         {
             Contract.Assert(model != null);

src/Microsoft.AspNet.OData.Shared/Builder/ODataConventionModelBuilder.cs

@@ -71,6 +71,9 @@ public partial class ODataConventionModelBuilder : ODataModelBuilder
             // IEdmFunctionImportConventions's
             new ActionLinkGenerationConvention(),
             new FunctionLinkGenerationConvention(),
+
+            // Documentation conventions
+            new DescriptionAnnotationConvention(),
         };
 
         // These hashset's keep track of edmtypes/navigation sources for which conventions

src/Microsoft.AspNet.OData.Shared/Builder/PropertyConfiguration.cs

@@ -15,6 +15,8 @@ namespace Microsoft.AspNet.OData.Builder
     public abstract class PropertyConfiguration
     {
         private string _name;
+        private string _description;
+        private string _longDescription;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="PropertyConfiguration"/> class.
@@ -40,7 +42,7 @@ protected PropertyConfiguration(PropertyInfo property, StructuralTypeConfigurati
             QueryConfiguration = new QueryConfiguration();
             DerivedTypeConstraints = new DerivedTypeConstraintConfiguration();
         }
-
+        
         /// <summary>
         /// Gets or sets the name of the property.
         /// </summary>
@@ -59,6 +61,24 @@ public string Name
 
                 _name = value;
             }
+        } 
+
+        /// <summary>
+        /// Gets or sets the summary for the property.
+        /// </summary>
+        public string Description
+        {
+            get => _description;
+            set => _description = value ?? throw Error.PropertyNull();
+        }
+
+        /// <summary>
+        /// Gets or sets the detailed description of the property.
+        /// </summary>
+        public string LongDescription
+        {
+            get => _longDescription;
+            set => _longDescription = value ?? throw Error.PropertyNull();
         }
 
         /// <summary>

src/Microsoft.AspNet.OData.Shared/Builder/StructuralTypeConfiguration.cs

@@ -23,6 +23,8 @@ public abstract class StructuralTypeConfiguration : IEdmTypeConfiguration
         private PropertyInfo _dynamicPropertyDictionary;
         private StructuralTypeConfiguration _baseType;
         private bool _baseTypeConfigured;
+        private string _description;
+        private string _longDescription;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="StructuralTypeConfiguration"/> class.
@@ -85,6 +87,24 @@ public virtual string FullName
             }
         }
 
+        /// <summary>
+        /// Gets or sets the summary for the property.
+        /// </summary>
+        public string Description
+        {
+	        get => _description;
+	        set => _description = value ?? throw Error.PropertyNull();
+        }
+
+        /// <summary>
+        /// Gets or sets the detailed description of the property.
+        /// </summary>
+        public string LongDescription
+        {
+	        get => _longDescription;
+	        set => _longDescription = value ?? throw Error.PropertyNull();
+        }
+
         /// <summary>
         /// Gets or sets the namespace of this EDM type.
         /// </summary>

src/Microsoft.AspNet.OData.Shared/Builder/StructuralTypeConfigurationOfTStructuralType.cs

@@ -653,6 +653,35 @@ public StructuralTypeConfiguration<TStructuralType> Count(QueryOptionSetting set
             return this;
         }
 
+        /// <summary>
+        /// Sets the description for this type.
+        /// </summary>
+        /// <param name="summary">A short description for this type.</param>
+        /// <param name="detailedDescription">A detailed description for this type.</param>
+        /// <returns></returns>
+        public StructuralTypeConfiguration<TStructuralType> HasDescription(string summary, string detailedDescription)
+        {
+	        _configuration.Description = summary;
+	        if (!string.IsNullOrEmpty(detailedDescription))
+	        {
+		        _configuration.LongDescription = detailedDescription;
+	        }
+
+	        return this;
+        }
+
+        /// <summary>
+        /// Sets the description for this type.
+        /// </summary>
+        /// <param name="summary">A short description for this type.</param>
+        /// <returns></returns>
+        public StructuralTypeConfiguration<TStructuralType> HasDescription(string summary)
+        {
+	        _configuration.Description = summary;
+
+	        return this;
+        }
+
         /// <summary>
         /// Sets sortable properties depends on <see cref="QueryOptionSetting"/> of this structural type.
         /// </summary>

src/Microsoft.AspNet.OData.Shared/Microsoft.AspNet.OData.Shared.projitems

@@ -14,9 +14,11 @@
     <Compile Include="$(MSBuildThisFileDirectory)Builder\Conventions\Attributes\DerivedTypeConstraintAttributeEdmPropertyConvention.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\Conventions\Attributes\MaxLengthAttributeEdmPropertyConvention.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\Conventions\Attributes\DefaultValueAttributeEdmPropertyConvention.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Builder\Conventions\DescriptionAnnotationConvention.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\DecimalPropertyConfiguration.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\DerivedTypeConstraintAttribute.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\DerivedTypeConstraintConfiguration.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Builder\Conventions\Attributes\DescriptionAttribute.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\LengthPropertyConfiguration.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Builder\PrecisionPropertyConfiguration.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)ClrEnumMemberAnnotation.cs" />
@@ -169,7 +171,7 @@
     <Compile Include="$(MSBuildThisFileDirectory)Builder\DynamicPropertyDictionaryAnnotation.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Query\Expressions\AggregationBinder.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Query\Expressions\ComputeBinder.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Query\Expressions\TransformationBinderBase.cs" />    
+    <Compile Include="$(MSBuildThisFileDirectory)Query\Expressions\TransformationBinderBase.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Query\ApplyQueryOption.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Query\Expressions\DynamicTypeWrapper.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Query\Expressions\ExpressionBinderBase.cs" />

test/UnitTest/Microsoft.AspNet.OData.Test.Shared/Builder/Conventions/ODataConventionModelBuilderTests.cs

@@ -10,6 +10,7 @@
 using System.Reflection;
 using System.Runtime.Serialization;
 using Microsoft.AspNet.OData.Builder;
+using Microsoft.AspNet.OData.Builder.Conventions.Attributes;
 using Microsoft.AspNet.OData.Formatter;
 using Microsoft.AspNet.OData.Query;
 using Microsoft.AspNet.OData.Test.Abstraction;
@@ -3134,6 +3135,90 @@ public void ConventionModelBuilder_Work_With_ExpilitPropertyDeclare()
             Assert.False(entityType.Properties().First(p => p.Name.Equals("UserType")).Type.IsNullable);
             Assert.False(entityType.Properties().First(p => p.Name.Equals("Contacts")).Type.IsNullable);
         }
+
+        [Fact]
+        public void ConventionModelBuilder_Description_Set_On_EntityType()
+        {
+            // Arrange
+            var builder = ODataConventionModelBuilderFactory.Create();
+
+            // Act 
+            var user = builder.EntitySet<IdentityUser>("IdentityUsers");
+            user.EntityType.HasKey(p => new { p.Provider, p.UserId });
+            user.EntityType.HasDescription("Summary", "Detailed description");
+            var edmModel = builder.GetEdmModel();
+
+            // Assert
+            Assert.NotNull(edmModel);
+            var entityType = edmModel.SchemaElements.OfType<IEdmEntityType>().First();
+            AssertAnnotations(entityType, edmModel);
+        }
+
+        private static void AssertAnnotations(IEdmVocabularyAnnotatable entityType, IEdmModel edmModel)
+        {
+	        var annotation = entityType.VocabularyAnnotations(edmModel).First(e => e.Term.Name == "Description");
+	        var value = Assert.IsType<EdmStringConstant>(annotation.Value);
+	        Assert.Equal("Summary", value.Value);
+	        annotation = entityType.VocabularyAnnotations(edmModel).First(e => e.Term.Name == "LongDescription");
+	        value = Assert.IsType<EdmStringConstant>(annotation.Value);
+	        Assert.Equal("Detailed description", value.Value);
+        }
+
+        [Fact]
+        public void ConventionModelBuilder_Description_Set_On_Property()
+        {
+            // Arrange
+            var builder = ODataConventionModelBuilderFactory.Create();
+
+            // Act 
+            var user = builder.EntitySet<IdentityUser>("IdentityUsers");
+            user.EntityType.HasKey(p => new { p.Provider, p.UserId });
+            var propertyConfiguration = user.EntityType.Property(i => i.Name);
+            propertyConfiguration.Description = "Summary";
+            propertyConfiguration.LongDescription = "Detailed description";
+            var edmModel = builder.GetEdmModel();
+
+            // Assert
+            Assert.NotNull(edmModel);
+            var entityType = edmModel.SchemaElements.OfType<IEdmEntityType>().First();
+            var property = entityType.Properties().First(p => p.Name == "Name");
+
+            AssertAnnotations(property, edmModel);
+        }
+
+        [Fact]
+        public void ConventionModelBuilder_Description_Set_On_Entity_Via_Description_Attribute()
+        {
+	        // Arrange
+	        var builder = ODataConventionModelBuilderFactory.Create();
+
+	        // Act 
+	        builder.EntitySet<DescriptionEntity>("DescriptionEntities");
+	        var edmModel = builder.GetEdmModel();
+
+	        // Assert
+	        Assert.NotNull(edmModel);
+	        var entityType = edmModel.SchemaElements.OfType<IEdmEntityType>().First();
+	        AssertAnnotations(entityType, edmModel);
+        }
+
+        [Fact]
+        public void ConventionModelBuilder_Description_Set_On_Property_Via_Description_Attribute()
+        {
+	        // Arrange
+	        var builder = ODataConventionModelBuilderFactory.Create();
+
+	        // Act 
+	        builder.EntitySet<DescriptionPropertyEntity>("IdentityUsers");
+	        var edmModel = builder.GetEdmModel();
+
+	        // Assert
+	        Assert.NotNull(edmModel);
+	        var entityType = edmModel.SchemaElements.OfType<IEdmEntityType>().First();
+	        var property = entityType.Properties().First(p => p.Name == "Id");
+
+	        AssertAnnotations(property, edmModel);
+        }
 
         [Fact]
         public void ConventionModelBuild_Work_With_AutoExpandEdmTypeAttribute()
@@ -3720,4 +3805,18 @@ public class MaxLengthEntity
 
         public string NonLength { get; set; }
     }
+
+    [Description("Summary", LongDescription = "Detailed description")]
+    public class DescriptionEntity
+    {
+        [Key]
+        public int Id { get; set; }
+    }
+
+    public class DescriptionPropertyEntity
+    {
+	    [Key]
+	    [Description("Summary", LongDescription = "Detailed description")]
+	    public int Id { get; set; }
+    }
 }