Query: Add XML docs for relational SQL tree (#20801)

src/EFCore.Relational/Query/Internal/SqlExpressionOptimizingExpressionVisitor.cs

@@ -121,9 +121,7 @@ private Expression VisitSelect(SelectExpression selectExpression)
                         newHaving,
                         newSelectExpression.Orderings.ToList(),
                         newSelectExpression.Limit,
-                        newSelectExpression.Offset,
-                        newSelectExpression.IsDistinct,
-                        newSelectExpression.Alias)
+                        newSelectExpression.Offset)
                     : newSelectExpression;
             }
 

src/EFCore.Relational/Query/NullabilityBasedSqlProcessingExpressionVisitor.cs

@@ -567,8 +567,7 @@ protected override Expression VisitSelect(SelectExpression selectExpression)
 
             return changed
                 ? selectExpression.Update(
-                    projections, tables, predicate, groupBy, having, orderings, limit, offset, selectExpression.IsDistinct,
-                    selectExpression.Alias)
+                    projections, tables, predicate, groupBy, having, orderings, limit, offset)
                 : selectExpression;
         }
 

src/EFCore.Relational/Query/RelationalQueryableMethodTranslatingExpressionVisitor.cs

@@ -98,7 +98,7 @@ protected override Expression VisitExtension(Expression extensionExpression)
                     var alias = (entityType.GetViewOrTableMappings().SingleOrDefault()?.Table.Name
                         ?? entityType.ShortName()).Substring(0, 1).ToLower();
 
-                    var translation = new TableValuedFunctionExpression(function.Schema, function.Name, arguments, alias);
+                    var translation = new TableValuedFunctionExpression(alias, function.Schema, function.Name, arguments);
                     var queryExpression = _sqlExpressionFactory.Select(entityType, translation);
 
                     return CreateShapedQueryExpression(entityType, queryExpression);

src/EFCore.Relational/Query/SqlExpressions/CaseExpression.cs

@@ -10,10 +10,25 @@
 
 namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions
 {
+    /// <summary>
+    ///     <para>
+    ///         An expression that represents a CASE statement in a SQL tree.
+    ///     </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 CaseExpression : SqlExpression
     {
         private readonly List<CaseWhenClause> _whenClauses = new List<CaseWhenClause>();
 
+        /// <summary>
+        ///     Creates a new instance of the <see cref="CaseExpression" /> class.
+        /// </summary>
+        /// <param name="operand"> An expression to compare with <see cref="CaseWhenClause.Test"/> in <see cref="WhenClauses"/>. </param>
+        /// <param name="whenClauses"> A list of <see cref="CaseWhenClause"/> to compare and get result from. </param>
+        /// <param name="elseResult"> A value to return if no <see cref="WhenClauses"/> matches, if any. </param>
         public CaseExpression(
             [NotNull] SqlExpression operand,
             [NotNull] IReadOnlyList<CaseWhenClause> whenClauses,
@@ -27,6 +42,11 @@ public CaseExpression(
             ElseResult = elseResult;
         }
 
+        /// <summary>
+        ///     Creates a new instance of the <see cref="CaseExpression" /> class.
+        /// </summary>
+        /// <param name="whenClauses"> A list of <see cref="CaseWhenClause"/> to evaluate condition and get result from. </param>
+        /// <param name="elseResult"> A value to return if no <see cref="WhenClauses"/> matches, if any. </param>
         public CaseExpression(
             [NotNull] IReadOnlyList<CaseWhenClause> whenClauses,
             [CanBeNull] SqlExpression elseResult = null)
@@ -36,10 +56,20 @@ public CaseExpression(
             ElseResult = elseResult;
         }
 
+        /// <summary>
+        ///     The value to compare in <see cref="WhenClauses"/>.
+        /// </summary>
         public virtual SqlExpression Operand { get; }
+        /// <summary>
+        ///     The list of <see cref="CaseWhenClause"/> to match <see cref="Operand"/> or evaluate condition to get result.
+        /// </summary>
         public virtual IReadOnlyList<CaseWhenClause> WhenClauses => _whenClauses;
+        /// <summary>
+        ///     The value to return if none of the <see cref="WhenClauses"/> matches.
+        /// </summary>
         public virtual SqlExpression ElseResult { get; }
 
+        /// <inheritdoc />
         protected override Expression VisitChildren(ExpressionVisitor visitor)
         {
             Check.NotNull(visitor, nameof(visitor));
@@ -72,6 +102,14 @@ protected override Expression VisitChildren(ExpressionVisitor visitor)
                 : this;
         }
 
+        /// <summary>
+        ///     Creates a new expression that is like this one, but using the supplied children. If all of the children are the same, it will
+        ///     return this expression.
+        /// </summary>
+        /// <param name="operand"> The <see cref="Operand"/> property of the result. </param>
+        /// <param name="whenClauses"> The <see cref="WhenClauses"/> property of the result. </param>
+        /// <param name="elseResult"> The <see cref="ElseResult"/> property of the result. </param>
+        /// <returns> This expression if no children changed, or an expression with the updated children. </returns>
         public virtual CaseExpression Update(
             [CanBeNull] SqlExpression operand,
             [NotNull] IReadOnlyList<CaseWhenClause> whenClauses,
@@ -82,6 +120,7 @@ public virtual CaseExpression Update(
                     : new CaseExpression(operand, whenClauses, elseResult))
                 : this;
 
+        /// <inheritdoc />
         public override void Print(ExpressionPrinter expressionPrinter)
         {
             Check.NotNull(expressionPrinter, nameof(expressionPrinter));
@@ -113,6 +152,7 @@ public override void Print(ExpressionPrinter expressionPrinter)
             expressionPrinter.AppendLine().Append("END");
         }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
             => obj != null
                 && (ReferenceEquals(this, obj)
@@ -125,6 +165,7 @@ private bool Equals(CaseExpression caseExpression)
                 && WhenClauses.SequenceEqual(caseExpression.WhenClauses)
                 && (ElseResult == null ? caseExpression.ElseResult == null : ElseResult.Equals(caseExpression.ElseResult));
 
+        /// <inheritdoc />
         public override int GetHashCode()
         {
             var hash = new HashCode();

src/EFCore.Relational/Query/SqlExpressions/CaseWhenClause.cs

@@ -7,8 +7,22 @@
 
 namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions
 {
+    /// <summary>
+    ///     <para>
+    ///         An expression that represents a WHEN...THEN... construct in a SQL tree.
+    ///     </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 CaseWhenClause
     {
+        /// <summary>
+        ///     Creates a new instance of the <see cref="CaseWhenClause" /> class.
+        /// </summary>
+        /// <param name="test"> A value to compare with <see cref="CaseExpression.Operand"/> or condition to evaluate. </param>
+        /// <param name="result"> A value to return if test succeeds. </param>
         public CaseWhenClause([NotNull] SqlExpression test, [NotNull] SqlExpression result)
         {
             Check.NotNull(test, nameof(test));
@@ -18,9 +32,16 @@ public CaseWhenClause([NotNull] SqlExpression test, [NotNull] SqlExpression resu
             Result = result;
         }
 
+        /// <summary>
+        ///     The value to compare with <see cref="CaseExpression.Operand"/> or the condition to evaluate.
+        /// </summary>
         public virtual SqlExpression Test { get; }
+        /// <summary>
+        ///     The value to return if <see cref="Test"/> succeeds.
+        /// </summary>
         public virtual SqlExpression Result { get; }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
             => obj != null
                 && (ReferenceEquals(this, obj)
@@ -31,6 +52,7 @@ private bool Equals(CaseWhenClause caseWhenClause)
             => Test.Equals(caseWhenClause.Test)
                 && Result.Equals(caseWhenClause.Result);
 
+        /// <inheritdoc />
         public override int GetHashCode() => HashCode.Combine(Test, Result);
     }
 }

src/EFCore.Relational/Query/SqlExpressions/CollateExpression.cs

@@ -8,8 +8,22 @@
 
 namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions
 {
+    /// <summary>
+    ///     <para>
+    ///         An expression that represents a COLLATE in a SQL tree.
+    ///     </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 CollateExpression : SqlExpression
     {
+        /// <summary>
+        ///     Creates a new instance of the <see cref="CollateExpression" /> class.
+        /// </summary>
+        /// <param name="operand"> An expression on which collation is applied. </param>
+        /// <param name="collation"> A collation value to use. </param>
         public CollateExpression([NotNull] SqlExpression operand, [NotNull] string collation)
             : base(operand.Type, operand.TypeMapping)
         {
@@ -20,16 +34,29 @@ public CollateExpression([NotNull] SqlExpression operand, [NotNull] string colla
             Collation = collation;
         }
 
+        /// <summary>
+        ///     The expression on which collation is applied.
+        /// </summary>
         public virtual SqlExpression Operand { get; }
+        /// <summary>
+        ///     The collation value to use.
+        /// </summary>
         public virtual string Collation { get; }
 
+        /// <inheritdoc />
         protected override Expression VisitChildren(ExpressionVisitor visitor)
         {
             Check.NotNull(visitor, nameof(visitor));
 
             return Update((SqlExpression)visitor.Visit(Operand));
         }
 
+        /// <summary>
+        ///     Creates a new expression that is like this one, but using the supplied children. If all of the children are the same, it will
+        ///     return this expression.
+        /// </summary>
+        /// <param name="operand"> The <see cref="Operand"/> property of the result. </param>
+        /// <returns> This expression if no children changed, or an expression with the updated children. </returns>
         public virtual CollateExpression Update([NotNull] SqlExpression operand)
         {
             Check.NotNull(operand, nameof(operand));
@@ -39,6 +66,7 @@ public virtual CollateExpression Update([NotNull] SqlExpression operand)
                 : this;
         }
 
+        /// <inheritdoc />
         public override void Print(ExpressionPrinter expressionPrinter)
         {
             Check.NotNull(expressionPrinter, nameof(expressionPrinter));
@@ -49,6 +77,7 @@ public override void Print(ExpressionPrinter expressionPrinter)
                 .Append(Collation);
         }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
             => obj != null
                 && (ReferenceEquals(this, obj)
@@ -60,6 +89,7 @@ private bool Equals(CollateExpression collateExpression)
                 && Operand.Equals(collateExpression.Operand)
                 && Collation.Equals(collateExpression.Collation, StringComparison.Ordinal);
 
+        /// <inheritdoc />
         public override int GetHashCode() => HashCode.Combine(base.GetHashCode(), Operand, Collation);
     }
 }

src/EFCore.Relational/Query/SqlExpressions/ColumnExpression.cs

@@ -10,6 +10,15 @@
 
 namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions
 {
+    /// <summary>
+    ///     <para>
+    ///         An expression that represents a column in a SQL tree.
+    ///     </para>
+    ///     <para>
+    ///         This type is typically used by database providers (and other extensions). It is generally
+    ///         not used in application code.
+    ///     </para>
+    /// </summary>
     [DebuggerDisplay("{DebuggerDisplay(),nq}")]
     // Class is sealed because there are no public/protected constructors. Can be unsealed if this is changed.
     public sealed class ColumnExpression : SqlExpression
@@ -49,20 +58,35 @@ private ColumnExpression(string name, TableExpressionBase table, Type type, Rela
             IsNullable = nullable;
         }
 
+        /// <summary>
+        ///     The name of the column.
+        /// </summary>
         public string Name { get; }
+        /// <summary>
+        ///     The table from which column is being referenced.
+        /// </summary>
         public TableExpressionBase Table { get; }
+        /// <summary>
+        ///     The bool value indicating if this column can have null values.
+        /// </summary>
         public bool IsNullable { get; }
 
+        /// <inheritdoc />
         protected override Expression VisitChildren(ExpressionVisitor visitor)
         {
             Check.NotNull(visitor, nameof(visitor));
 
             return this;
         }
 
+        /// <summary>
+        ///     Makes this column nullable.
+        /// </summary>
+        /// <returns> A new expression which has <see cref="IsNullable"/> property set to true. </returns>
         public ColumnExpression MakeNullable()
             => new ColumnExpression(Name, Table, Type.MakeNullable(), TypeMapping, true);
 
+        /// <inheritdoc />
         public override void Print(ExpressionPrinter expressionPrinter)
         {
             Check.NotNull(expressionPrinter, nameof(expressionPrinter));
@@ -71,6 +95,7 @@ public override void Print(ExpressionPrinter expressionPrinter)
             expressionPrinter.Append(Name);
         }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
             => obj != null
                 && (ReferenceEquals(this, obj)
@@ -83,6 +108,7 @@ private bool Equals(ColumnExpression columnExpression)
                 && Table.Equals(columnExpression.Table)
                 && IsNullable == columnExpression.IsNullable;
 
+        /// <inheritdoc />
         public override int GetHashCode() => HashCode.Combine(base.GetHashCode(), Name, Table, IsNullable);
 
         private string DebuggerDisplay() => $"{Table.Alias}.{Name}";

src/EFCore.Relational/Query/SqlExpressions/CrossApplyExpression.cs

@@ -7,20 +7,40 @@
 
 namespace Microsoft.EntityFrameworkCore.Query.SqlExpressions
 {
+    /// <summary>
+    ///     <para>
+    ///         An expression that represents a CROSS APPLY in a SQL tree.
+    ///     </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 CrossApplyExpression : JoinExpressionBase
     {
+        /// <summary>
+        ///     Creates a new instance of the <see cref="CrossApplyExpression" /> class.
+        /// </summary>
+        /// <param name="table"> A table source to CROSS APPLY with. </param>
         public CrossApplyExpression([NotNull] TableExpressionBase table)
             : base(table)
         {
         }
 
+        /// <inheritdoc />
         protected override Expression VisitChildren(ExpressionVisitor visitor)
         {
             Check.NotNull(visitor, nameof(visitor));
 
             return Update((TableExpressionBase)visitor.Visit(Table));
         }
 
+        /// <summary>
+        ///     Creates a new expression that is like this one, but using the supplied children. If all of the children are the same, it will
+        ///     return this expression.
+        /// </summary>
+        /// <param name="table"> The <see cref="P:Table"/> property of the result. </param>
+        /// <returns> This expression if no children changed, or an expression with the updated children. </returns>
         public virtual CrossApplyExpression Update([NotNull] TableExpressionBase table)
         {
             Check.NotNull(table, nameof(table));
@@ -30,6 +50,7 @@ public virtual CrossApplyExpression Update([NotNull] TableExpressionBase table)
                 : this;
         }
 
+        /// <inheritdoc />
         public override void Print(ExpressionPrinter expressionPrinter)
         {
             Check.NotNull(expressionPrinter, nameof(expressionPrinter));
@@ -38,6 +59,7 @@ public override void Print(ExpressionPrinter expressionPrinter)
             expressionPrinter.Visit(Table);
         }
 
+        /// <inheritdoc />
         public override bool Equals(object obj)
             => obj != null
                 && (ReferenceEquals(this, obj)
@@ -47,6 +69,7 @@ public override bool Equals(object obj)
         private bool Equals(CrossApplyExpression crossApplyExpression)
             => base.Equals(crossApplyExpression);
 
+        /// <inheritdoc />
         public override int GetHashCode() => base.GetHashCode();
     }
 }