Integrate comments by @smitpatel into source

See #18874 (comment)

src/EFCore/Query/Internal/NavigationExpandingExpressionVisitor.ExpressionVisitors.cs

@@ -15,6 +15,10 @@ namespace Microsoft.EntityFrameworkCore.Query.Internal
 {
     public partial class NavigationExpandingExpressionVisitor
     {
+        /// <summary>
+        ///     Expands navigations in the given tree for given source.
+        ///     Optionally also expands navigations for includes.
+        /// </summary>
         private class ExpandingExpressionVisitor : ExpressionVisitor
         {
             private readonly NavigationExpandingExpressionVisitor _navigationExpandingExpressionVisitor;
@@ -28,6 +32,12 @@ public ExpandingExpressionVisitor(
                 _source = source;
             }
 
+            /// <summary>
+            ///     Expands navigations in the given tree for given source.
+            ///     Optionally also expands navigations for includes.
+            /// </summary>
+            /// <param name="expression"> The query expression tree. </param>
+            /// <param name="applyIncludes"> Whether to also expand navigations for includes. </param>
             public Expression Expand(Expression expression, bool applyIncludes = false)
             {
                 expression = Visit(expression);
@@ -301,6 +311,10 @@ protected Expression ExpandNavigation(
             }
         }
 
+        /// <summary>
+        ///     Expands an include tree. This is separate and needed because we may need to reconstruct parts of
+        ///     <see cref="NewExpression"/> to apply includes.
+        /// </summary>
         private sealed class IncludeExpandingExpressionVisitor : ExpandingExpressionVisitor
         {
             private readonly bool _isTracking;
@@ -502,6 +516,10 @@ private Expression ExpandIncludesHelper(Expression root, EntityReference entityR
             }
         }
 
+        /// <summary>
+        ///     <see cref="NavigationExpansionExpression"/> remembers the pending selector so we don't expand
+        ///     navigations unless we need to. This visitor applies them when we need to.
+        /// </summary>
         private sealed class PendingSelectorExpandingExpressionVisitor : ExpressionVisitor
         {
             private readonly NavigationExpandingExpressionVisitor _visitor;
@@ -534,6 +552,9 @@ public override Expression Visit(Expression expression)
             }
         }
 
+        /// <summary>
+        ///     Removes custom expressions from tree and converts it to LINQ again.
+        /// </summary>
         private sealed class ReducingExpressionVisitor : ExpressionVisitor
         {
             public override Expression Visit(Expression expression)
@@ -596,6 +617,11 @@ public override Expression Visit(Expression expression)
             }
         }
 
+        /// <summary>
+        ///     Marks <see cref="EntityReference"/> as nullable when coming from a left join.
+        ///     Nullability is required to figure out if the navigation from this entity should be a left join or
+        ///     an inner join.
+        /// </summary>
         private sealed class EntityReferenceOptionalMarkingExpressionVisitor : ExpressionVisitor
         {
             public override Expression Visit(Expression expression)
@@ -611,6 +637,9 @@ public override Expression Visit(Expression expression)
             }
         }
 
+        /// <summary>
+        ///     Allows self reference of query root inside query filters/defining queries.
+        /// </summary>
         private sealed class SelfReferenceEntityQueryableRewritingExpressionVisitor : ExpressionVisitor
         {
             private readonly NavigationExpandingExpressionVisitor _navigationExpandingExpressionVisitor;

src/EFCore/Query/Internal/NavigationExpandingExpressionVisitor.Expressions.cs

@@ -78,6 +78,9 @@ public virtual void Print(ExpressionPrinter expressionPrinter)
             }
         }
 
+        /// <summary>
+        ///     A tree structure of includes for a given entity type in <see cref="EntityReference"/>.
+        /// </summary>
         protected class IncludeTreeNode : Dictionary<INavigation, IncludeTreeNode>
         {
             private EntityReference _entityReference;
@@ -162,6 +165,10 @@ private bool Equals(IncludeTreeNode includeTreeNode)
             public override int GetHashCode() => HashCode.Combine(base.GetHashCode(), EntityType);
         }
 
+        /// <summary>
+        ///     Stores information about the current queryable, its source, structure of projection, parameter type etc.
+        ///     This is needed because once navigations are expanded we still remember these to avoid expanding again.
+        /// </summary>
         protected class NavigationExpansionExpression : Expression, IPrintableExpression
         {
             private readonly List<(MethodInfo OrderingMethod, Expression KeySelector)> _pendingOrderings
@@ -250,6 +257,11 @@ public virtual void Print(ExpressionPrinter expressionPrinter)
             }
         }
 
+        /// <summary>
+        ///     A leaf node on navigation tree, representing projection structures of
+        ///     <see cref="NavigationExpansionExpression"/>. Contains <see cref="NavigationTreeExpression.Value"/>,
+        ///     which can be <see cref="NewExpression"/> or <see cref="EntityReference"/>.
+        /// </summary>
         protected class NavigationTreeExpression : NavigationTreeNode, IPrintableExpression
         {
             public NavigationTreeExpression(Expression value)
@@ -258,6 +270,9 @@ public NavigationTreeExpression(Expression value)
                 Value = value;
             }
 
+            /// <summary>
+            ///     Either <see cref="NewExpression"/> or <see cref="EntityReference"/>.
+            /// </summary>
             public virtual Expression Value { get; private set; }
 
             protected override Expression VisitChildren(ExpressionVisitor visitor)
@@ -287,6 +302,11 @@ public virtual void Print(ExpressionPrinter expressionPrinter)
             }
         }
 
+        /// <summary>
+        ///     A node in navigation binary tree. A navigation tree is a structure of the current parameter, which
+        ///     would be transparent identifier (hence it's a binary structure). This allows us to easily condense to
+        ///     inner/outer member access.
+        /// </summary>
         protected class NavigationTreeNode : Expression
         {
             private NavigationTreeNode _parent;
@@ -338,6 +358,10 @@ public virtual Expression GetExpression()
             }
         }
 
+        /// <summary>
+        ///     Owned navigations are not expanded, since they map differently in different providers.
+        ///     This remembers such references so that they can still be treated like navigations.
+        /// </summary>
         protected class OwnedNavigationReference : Expression
         {
             public OwnedNavigationReference(Expression parent, INavigation navigation, EntityReference entityReference)