Query: Add rest of XML docs for relational layer (#20838)

src/EFCore.Cosmos/Metadata/Conventions/StoreKeyConvention.cs

@@ -5,6 +5,7 @@
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Cosmos.Metadata.Internal;
 using Microsoft.EntityFrameworkCore.Cosmos.ValueGeneration.Internal;
+using Microsoft.EntityFrameworkCore.Infrastructure;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
 using Microsoft.EntityFrameworkCore.Metadata.Conventions.Infrastructure;
 using Microsoft.EntityFrameworkCore.Utilities;
@@ -28,10 +29,23 @@ public class StoreKeyConvention :
         IEntityTypeAnnotationChangedConvention,
         IEntityTypeBaseTypeChangedConvention
     {
-#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
+        /// <summary>
+        ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+        ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+        ///     any release. You should only use it directly in your code with extreme caution and knowing that
+        ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+        /// </summary>
+        [EntityFrameworkInternal]
         public static readonly string IdPropertyName = "id";
+
+        /// <summary>
+        ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+        ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+        ///     any release. You should only use it directly in your code with extreme caution and knowing that
+        ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+        /// </summary>
+        [EntityFrameworkInternal]
         public static readonly string JObjectPropertyName = "__jObject";
-#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member
 
         /// <summary>
         ///     Creates a new instance of <see cref="StoreKeyConvention" />.

src/EFCore.Relational/EFCore.Relational.csproj

@@ -7,7 +7,6 @@
     <AssemblyName>Microsoft.EntityFrameworkCore.Relational</AssemblyName>
     <RootNamespace>Microsoft.EntityFrameworkCore</RootNamespace>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <NoWarn>$(NoWarn);1591</NoWarn>
     <CodeAnalysisRuleSet>..\..\EFCore.ruleset</CodeAnalysisRuleSet>
   </PropertyGroup>
 

src/EFCore.Relational/Extensions/RelationalDbFunctionsExtensions.cs

@@ -9,6 +9,10 @@
 // ReSharper disable once CheckNamespace
 namespace Microsoft.EntityFrameworkCore
 {
+    /// <summary>
+    ///     Provides CLR methods that get translated to database functions when used in LINQ to Entities queries.
+    ///     The methods on this class are accessed via <see cref="EF.Functions" />.
+    /// </summary>
     public static class RelationalDbFunctionsExtensions
     {
         /// <summary>

src/EFCore.Relational/Infrastructure/RelationalPropertyExtensions.cs

@@ -8,6 +8,9 @@
 
 namespace Microsoft.EntityFrameworkCore.Infrastructure
 {
+    /// <summary>
+    ///     Relational extension methods for <see cref="IProperty" />.
+    /// </summary>
     public static class RelationalPropertyExtensions
     {
         /// <summary>

src/EFCore.Relational/Metadata/Conventions/RelationalQueryFilterDefiningQueryRewritingConvention.cs

@@ -11,6 +11,7 @@
 
 namespace Microsoft.EntityFrameworkCore.Metadata.Conventions
 {
+    /// <inheritdoc />
     public class RelationalQueryFilterDefiningQueryRewritingConvention : QueryFilterDefiningQueryRewritingConvention
     {
         /// <summary>
@@ -26,13 +27,19 @@ public RelationalQueryFilterDefiningQueryRewritingConvention(
             DbSetAccessRewriter = new RelationalDbSetAccessRewritingExpressionVisitor(Dependencies.ContextType);
         }
 
+        /// <inheritdoc />
         protected class RelationalDbSetAccessRewritingExpressionVisitor : DbSetAccessRewritingExpressionVisitor
         {
+            /// <summary>
+            ///     Creates a new instance of <see cref="RelationalDbSetAccessRewritingExpressionVisitor" />.
+            /// </summary>
+            /// <param name="contextType"> The clr type of derived DbContext. </param>
             public RelationalDbSetAccessRewritingExpressionVisitor(Type contextType)
                 : base(contextType)
             {
             }
 
+            /// <inheritdoc />
             protected override Expression VisitMethodCall(MethodCallExpression methodCallExpression)
             {
                 Check.NotNull(methodCallExpression, nameof(methodCallExpression));

src/EFCore.Relational/Metadata/Conventions/TableSharingConcurrencyTokenConvention.cs

@@ -20,6 +20,8 @@ namespace Microsoft.EntityFrameworkCore.Metadata.Conventions
     /// </summary>
     public class TableSharingConcurrencyTokenConvention : IModelFinalizingConvention
     {
+        private const string ConcurrencyPropertyPrefix = "_TableSharingConcurrencyTokenConvention_";
+
         /// <summary>
         ///     Creates a new instance of <see cref="TableSharingConcurrencyTokenConvention" />.
         /// </summary>
@@ -37,8 +39,6 @@ public TableSharingConcurrencyTokenConvention(
         /// </summary>
         protected virtual ProviderConventionSetBuilderDependencies Dependencies { get; }
 
-        public static readonly string ConcurrencyPropertyPrefix = "_TableSharingConcurrencyTokenConvention_";
-
         /// <inheritdoc />
         public virtual void ProcessModelFinalizing(
             IConventionModelBuilder modelBuilder,

src/EFCore.Relational/Query/EntityProjectionExpression.cs

@@ -12,6 +12,15 @@
 
 namespace Microsoft.EntityFrameworkCore.Query
 {
+    /// <summary>
+    ///     <para>
+    ///         An expression that represents an entity in the projection of <see cref="SelectExpression"/>.
+    ///     </para>
+    ///     <para>
+    ///         This type is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
     public class EntityProjectionExpression : Expression
     {
         private readonly IDictionary<IProperty, ColumnExpression> _propertyExpressionsCache
@@ -23,6 +32,12 @@ private readonly IDictionary<INavigation, EntityShaperExpression> _navigationExp
         private readonly TableExpressionBase _innerTable;
         private readonly bool _nullable;
 
+        /// <summary>
+        ///     Creates a new instance of the <see cref="EntityProjectionExpression" /> class.
+        /// </summary>
+        /// <param name="entityType"> The entity type to shape. </param>
+        /// <param name="innerTable"> The table from which entity columns are being projected out. </param>
+        /// <param name="nullable"> A bool value indicating whether this entity instance can be null. </param>
         public EntityProjectionExpression([NotNull] IEntityType entityType, [NotNull] TableExpressionBase innerTable, bool nullable)
         {
             Check.NotNull(entityType, nameof(entityType));
@@ -33,6 +48,11 @@ public EntityProjectionExpression([NotNull] IEntityType entityType, [NotNull] Ta
             _nullable = nullable;
         }
 
+        /// <summary>
+        ///     Creates a new instance of the <see cref="EntityProjectionExpression" /> class.
+        /// </summary>
+        /// <param name="entityType"> The entity type to shape. </param>
+        /// <param name="propertyExpressions"> A dictionary of column expressions corresponding to properties of the entity type. </param>
         public EntityProjectionExpression([NotNull] IEntityType entityType, [NotNull] IDictionary<IProperty, ColumnExpression> propertyExpressions)
         {
             Check.NotNull(entityType, nameof(entityType));
@@ -42,10 +62,16 @@ public EntityProjectionExpression([NotNull] IEntityType entityType, [NotNull] ID
             _propertyExpressionsCache = propertyExpressions;
         }
 
+        /// <summary>
+        ///     The entity type being projected out.
+        /// </summary>
         public virtual IEntityType EntityType { get; }
+        /// <inheritdoc />
         public sealed override ExpressionType NodeType => ExpressionType.Extension;
+        /// <inheritdoc />
         public override Type Type => EntityType.ClrType;
 
+        /// <inheritdoc />
         protected override Expression VisitChildren(ExpressionVisitor visitor)
         {
             Check.NotNull(visitor, nameof(visitor));
@@ -74,6 +100,10 @@ protected override Expression VisitChildren(ExpressionVisitor visitor)
                 : this;
         }
 
+        /// <summary>
+        ///     Makes entity instance in projection nullable.
+        /// </summary>
+        /// <returns> A new entity projection expression which can project nullable entity. </returns>
         public virtual EntityProjectionExpression MakeNullable()
         {
             if (_innerTable != null)
@@ -90,6 +120,11 @@ public virtual EntityProjectionExpression MakeNullable()
             return new EntityProjectionExpression(EntityType, newCache);
         }
 
+        /// <summary>
+        ///     Updates the entity type being projected out to one of the derived type.
+        /// </summary>
+        /// <param name="derivedType"> A derived entity type which should be projected. </param>
+        /// <returns> A new entity projection expression which has the derived type being projected. </returns>
         public virtual EntityProjectionExpression UpdateEntityType([NotNull] IEntityType derivedType)
         {
             Check.NotNull(derivedType, nameof(derivedType));
@@ -113,6 +148,11 @@ public virtual EntityProjectionExpression UpdateEntityType([NotNull] IEntityType
             return new EntityProjectionExpression(derivedType, propertyExpressionCache);
         }
 
+        /// <summary>
+        ///     Binds a property with this entity projection to get the SQL representation.
+        /// </summary>
+        /// <param name="property"> A property to bind. </param>
+        /// <returns> A column which is a SQL representation of the property. </returns>
         public virtual ColumnExpression BindProperty([NotNull] IProperty property)
         {
             Check.NotNull(property, nameof(property));
@@ -137,6 +177,11 @@ public virtual ColumnExpression BindProperty([NotNull] IProperty property)
             return expression;
         }
 
+        /// <summary>
+        ///     Adds a navigation binding for this entity projection when the target entity type of the navigation is owned or weak.
+        /// </summary>
+        /// <param name="navigation"> A navigation to add binding for. </param>
+        /// <param name="entityShaper"> An entity shaper expression for the target type. </param>
         public virtual void AddNavigationBinding([NotNull] INavigation navigation, [NotNull] EntityShaperExpression entityShaper)
         {
             Check.NotNull(navigation, nameof(navigation));
@@ -156,6 +201,12 @@ public virtual void AddNavigationBinding([NotNull] INavigation navigation, [NotN
             _navigationExpressionsCache[navigation] = entityShaper;
         }
 
+        /// <summary>
+        ///     Binds a navigation with this entity projection to get entity shaper for the target entity type of the navigation which was
+        ///     previously added using <see cref="AddNavigationBinding(INavigation, EntityShaperExpression)"/> method.
+        /// </summary>
+        /// <param name="navigation"> A navigation to bind. </param>
+        /// <returns> An entity shaper expression for the target entity type of the navigation. </returns>
         public virtual EntityShaperExpression BindNavigation([NotNull] INavigation navigation)
         {
             Check.NotNull(navigation, nameof(navigation));

src/EFCore.Relational/Query/ExpressionExtensions.cs

@@ -9,13 +9,32 @@
 
 namespace Microsoft.EntityFrameworkCore.Query
 {
+    /// <summary>
+    ///     <para>
+    ///         Extension methods for <see cref="Expression" /> types.
+    ///     </para>
+    ///     <para>
+    ///         This type is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
     public static class ExpressionExtensions
     {
+        /// <summary>
+        ///     Checks if the given sql unary expression represents a logical NOT operation.
+        /// </summary>
+        /// <param name="sqlUnaryExpression"> A sql unary expression to check. </param>
+        /// <returns> A bool value indicating if the given expression represents a logical NOT operation. </returns>
         public static bool IsLogicalNot([NotNull] this SqlUnaryExpression sqlUnaryExpression)
             => sqlUnaryExpression.OperatorType == ExpressionType.Not
                 && (sqlUnaryExpression.Type == typeof(bool)
                     || sqlUnaryExpression.Type == typeof(bool?));
 
+        /// <summary>
+        ///     Infers type mapping from given <see cref="SqlExpression"/>s.
+        /// </summary>
+        /// <param name="expressions"> Expressions to search for to find the type mapping. </param>
+        /// <returns> A relational type mapping inferred from the expressions. </returns>
         public static RelationalTypeMapping InferTypeMapping([NotNull] params SqlExpression[] expressions)
         {
             Check.NotNull(expressions, nameof(expressions));

src/EFCore.Relational/Query/IMemberTranslator.cs

@@ -2,14 +2,31 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
+using System.Linq.Expressions;
 using System.Reflection;
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
 
 namespace Microsoft.EntityFrameworkCore.Query
 {
+    /// <summary>
+    ///     <para>
+    ///         A SQL translator for LINQ <see cref="MemberExpression" /> expression.
+    ///     </para>
+    ///     <para>
+    ///         This interface is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
     public interface IMemberTranslator
     {
+        /// <summary>
+        ///     Translates a LINQ <see cref="MemberExpression"/> to a SQL equivalent.
+        /// </summary>
+        /// <param name="instance"> A SQL representation of <see cref="MemberExpression.Expression"/>. </param>
+        /// <param name="member"> The member info from <see cref="MemberExpression.Member"/>. </param>
+        /// <param name="returnType"> The return type from <see cref="P:MemberExpression.Type"/>. </param>
+        /// <returns> A SQL translation of the <see cref="MemberExpression"/>. </returns>
         SqlExpression Translate([CanBeNull] SqlExpression instance, [NotNull] MemberInfo member, [NotNull] Type returnType);
     }
 }

src/EFCore.Relational/Query/IMemberTranslatorPlugin.cs

@@ -8,7 +8,7 @@ namespace Microsoft.EntityFrameworkCore.Query
 {
     /// <summary>
     ///     <para>
-    ///         Represents plugin member translators.
+    ///         Represents plugin for <see cref="IMemberTranslator"/>.
     ///     </para>
     ///     <para>
     ///         The service lifetime is <see cref="ServiceLifetime.Singleton" /> and multiple registrations

src/EFCore.Relational/Query/IMemberTranslatorProvider.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
+using System.Linq.Expressions;
 using System.Reflection;
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
@@ -11,7 +12,7 @@ namespace Microsoft.EntityFrameworkCore.Query
 {
     /// <summary>
     ///     <para>
-    ///         Provides translations for object members to <see cref="SqlExpression" /> instances.
+    ///         Provides translations for LINQ <see cref="MemberExpression" /> expressions.
     ///     </para>
     ///     <para>
     ///         The service lifetime is <see cref="ServiceLifetime.Singleton" />. This means a single instance
@@ -21,6 +22,13 @@ namespace Microsoft.EntityFrameworkCore.Query
     /// </summary>
     public interface IMemberTranslatorProvider
     {
+        /// <summary>
+        ///     Translates a LINQ <see cref="MemberExpression"/> to a SQL equivalent.
+        /// </summary>
+        /// <param name="instance"> A SQL representation of <see cref="MemberExpression.Expression"/>. </param>
+        /// <param name="member"> The member info from <see cref="MemberExpression.Member"/>. </param>
+        /// <param name="returnType"> The return type from <see cref="P:MemberExpression.Type"/>. </param>
+        /// <returns> A SQL translation of the <see cref="MemberExpression"/>. </returns>
         SqlExpression Translate([CanBeNull] SqlExpression instance, [NotNull] MemberInfo member, [NotNull] Type returnType);
     }
 }

src/EFCore.Relational/Query/IMethodCallTranslator.cs

@@ -2,14 +2,31 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System.Collections.Generic;
+using System.Linq.Expressions;
 using System.Reflection;
 using JetBrains.Annotations;
 using Microsoft.EntityFrameworkCore.Query.SqlExpressions;
 
 namespace Microsoft.EntityFrameworkCore.Query
 {
+    /// <summary>
+    ///     <para>
+    ///         A SQL translator for LINQ <see cref="MethodCallExpression" /> expression.
+    ///     </para>
+    ///     <para>
+    ///         This interface is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
     public interface IMethodCallTranslator
     {
+        /// <summary>
+        ///     Translates a LINQ <see cref="MethodCallExpression"/> to a SQL equivalent.
+        /// </summary>
+        /// <param name="instance"> A SQL representation of <see cref="MethodCallExpression.Object"/>. </param>
+        /// <param name="method"> The method info from <see cref="MethodCallExpression.Method"/>. </param>
+        /// <param name="arguments"> SQL representations of <see cref="MethodCallExpression.Arguments"/>. </param>
+        /// <returns> A SQL translation of the <see cref="MethodCallExpression"/>. </returns>
         SqlExpression Translate(
             [CanBeNull] SqlExpression instance, [NotNull] MethodInfo method, [NotNull] IReadOnlyList<SqlExpression> arguments);
     }

src/EFCore.Relational/Query/IMethodCallTranslatorPlugin.cs

@@ -8,7 +8,7 @@ namespace Microsoft.EntityFrameworkCore.Query
 {
     /// <summary>
     ///     <para>
-    ///         Represents plugin method call translators.
+    ///         Represents plugin for <see cref="IMethodCallTranslator"/>.
     ///     </para>
     ///     <para>
     ///         The service lifetime is <see cref="ServiceLifetime.Singleton" /> and multiple registrations