Add query documentation in EF Core (#20573)

Enable warning 1591

Will do relational assembly in other pass hence disabled in that csproj.

Also,
Make EntityMaterializerSource public internal
Make QueryableMethods to be shared internal
Make IParameterValues public internal

Directory.Build.props

@@ -30,6 +30,11 @@
     <PackageProjectUrl>https://docs.microsoft.com/ef/core/</PackageProjectUrl>
   </PropertyGroup>
 
+  <!-- HACK: Work around #15093 -->
+  <PropertyGroup>
+    <NoWarn>$(NoWarn.Replace(';1591', ''))</NoWarn>
+  </PropertyGroup>
+
   <ItemGroup>
     <EmbeddedResource Include="**\*.rd.xml" />
   </ItemGroup>

src/EFCore.Cosmos/Diagnostics/Internal/CosmosLoggerExtensions.cs

@@ -51,6 +51,12 @@ public static class CosmosLoggerExtensions
                 cosmosSqlQuery.Query);
         }
 
+        /// <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>
         public static void ExecutingReadItem(
             [NotNull] this IDiagnosticsLogger<DbLoggerCategory.Database.Command> diagnosticsLogger,
             [NotNull] string partitionKey,

src/EFCore.Cosmos/Infrastructure/Internal/CosmosDbOptionExtension.cs

@@ -215,6 +215,12 @@ public virtual CosmosOptionsExtension WithConnectionMode(ConnectionMode connecti
         /// </summary>
         protected virtual CosmosOptionsExtension Clone() => new CosmosOptionsExtension(this);
 
+        /// <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>
         public virtual void ApplyServices(IServiceCollection services)
             => services.AddEntityFrameworkCosmos();
 

src/EFCore.Cosmos/Infrastructure/Internal/ICosmosSingletonOptions.cs

@@ -47,6 +47,12 @@ public interface ICosmosSingletonOptions : ISingletonOptions
         /// </summary>
         string Region { get; }
 
+        /// <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>
         ConnectionMode? ConnectionMode { get; }
     }
 }

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

@@ -28,8 +28,10 @@ public class StoreKeyConvention :
         IEntityTypeAnnotationChangedConvention,
         IEntityTypeBaseTypeChangedConvention
     {
+#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
         public static readonly string IdPropertyName = "id";
         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.Cosmos/Query/Internal/CosmosProjectionBindingExpressionVisitor.cs

@@ -264,6 +264,12 @@ protected override Expression VisitMember(MemberExpression memberExpression)
             }
         }
 
+        /// <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>
         protected override Expression VisitMethodCall(MethodCallExpression methodCallExpression)
         {
             Check.NotNull(methodCallExpression, nameof(methodCallExpression));

src/EFCore.Cosmos/Query/Internal/CosmosQueryCompilationContext.cs

@@ -6,15 +6,32 @@
 
 namespace Microsoft.EntityFrameworkCore.Cosmos.Query.Internal
 {
+    /// <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>
     public class CosmosQueryCompilationContext : QueryCompilationContext
     {
-        public virtual string PartitionKeyFromExtension { get; internal set; }
-
+        /// <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>
         public CosmosQueryCompilationContext(
             [NotNull] QueryCompilationContextDependencies dependencies, bool async)
             : base(dependencies, async)
         {
-
         }
+
+        /// <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>
+        public virtual string PartitionKeyFromExtension { get; internal set; }
     }
 }

src/EFCore.Cosmos/Query/Internal/CosmosQueryCompilationContextFactory.cs

@@ -10,7 +10,10 @@ namespace Microsoft.EntityFrameworkCore.Cosmos.Query.Internal
 {
     /// <summary>
     ///     <para>
-    ///         A factory for creating <see cref="CosmosQueryCompilationContext" /> instances.
+    ///         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.
     ///     </para>
     ///     <para>
     ///         The service lifetime is <see cref="ServiceLifetime.Scoped" />. This means that each
@@ -23,12 +26,24 @@ public class CosmosQueryCompilationContextFactory : IQueryCompilationContextFact
     {
         private readonly QueryCompilationContextDependencies _dependencies;
 
+        /// <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>
         public CosmosQueryCompilationContextFactory([NotNull] QueryCompilationContextDependencies dependencies)
         {
             Check.NotNull(dependencies, nameof(dependencies));
             _dependencies = dependencies;
         }
 
+        /// <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>
         public virtual QueryCompilationContext Create(bool async)
             => new CosmosQueryCompilationContext(_dependencies, async);
     }

src/EFCore.Cosmos/Query/Internal/CosmosQueryMetadataExtractingExpressionVisitor.cs

@@ -7,16 +7,34 @@
 
 namespace Microsoft.EntityFrameworkCore.Cosmos.Query.Internal
 {
+    /// <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>
     public class CosmosQueryMetadataExtractingExpressionVisitor : ExpressionVisitor
     {
         private readonly CosmosQueryCompilationContext _cosmosQueryCompilationContext;
 
+        /// <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>
         public CosmosQueryMetadataExtractingExpressionVisitor([NotNull] CosmosQueryCompilationContext cosmosQueryCompilationContext)
         {
             Check.NotNull(cosmosQueryCompilationContext, nameof(cosmosQueryCompilationContext));
             _cosmosQueryCompilationContext = cosmosQueryCompilationContext;
         }
 
+        /// <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>
         protected override Expression VisitMethodCall(MethodCallExpression methodCallExpression)
         {
             if (methodCallExpression.Method.IsGenericMethod

src/EFCore.Cosmos/Query/Internal/CosmosQueryTranslationPreprocessor.cs

@@ -7,11 +7,22 @@
 
 namespace Microsoft.EntityFrameworkCore.Cosmos.Query.Internal
 {
+    /// <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>
     public class CosmosQueryTranslationPreprocessor : QueryTranslationPreprocessor
     {
-
         private readonly CosmosQueryCompilationContext _queryCompilationContext;
 
+        /// <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>
         public CosmosQueryTranslationPreprocessor(
             [NotNull] QueryTranslationPreprocessorDependencies dependencies,
             [NotNull] CosmosQueryCompilationContext cosmosQueryCompilationContext)
@@ -20,9 +31,15 @@ public class CosmosQueryTranslationPreprocessor : QueryTranslationPreprocessor
             _queryCompilationContext = cosmosQueryCompilationContext;
         }
 
-        public override Expression NormalizeQueryableMethodCall(Expression query)
+        /// <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>
+        public override Expression NormalizeQueryableMethod(Expression query)
         {
-            query = base.NormalizeQueryableMethodCall(query);
+            query = base.NormalizeQueryableMethod(query);
 
             query = new CosmosQueryMetadataExtractingExpressionVisitor(_queryCompilationContext).Visit(query);
 

src/EFCore.Cosmos/Query/Internal/CosmosQueryTranslationPreprocessorFactory.cs

@@ -10,7 +10,10 @@ namespace Microsoft.EntityFrameworkCore.Cosmos.Query.Internal
 {
     /// <summary>
     ///     <para>
-    ///         A factory for creating <see cref="CosmosQueryTranslationPreprocessor" /> instances.
+    ///         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.
     ///     </para>
     ///     <para>
     ///         The service lifetime is <see cref="ServiceLifetime.Singleton" />. This means a single instance
@@ -22,13 +25,25 @@ public class CosmosQueryTranslationPreprocessorFactory : IQueryTranslationPrepro
     {
         private readonly QueryTranslationPreprocessorDependencies _dependencies;
 
+        /// <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>
         public CosmosQueryTranslationPreprocessorFactory(
             [NotNull] QueryTranslationPreprocessorDependencies dependencies)
         {
             Check.NotNull(dependencies, nameof(dependencies));
             _dependencies = dependencies;
         }
 
+        /// <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>
         public virtual QueryTranslationPreprocessor Create(QueryCompilationContext queryCompilationContext)
             => new CosmosQueryTranslationPreprocessor(_dependencies,  (CosmosQueryCompilationContext)queryCompilationContext);
     }

src/EFCore.Cosmos/Query/Internal/CosmosQueryableMethodTranslatingExpressionVisitor.cs

@@ -42,7 +42,7 @@ public class CosmosQueryableMethodTranslatingExpressionVisitor : QueryableMethod
             [NotNull] ISqlExpressionFactory sqlExpressionFactory,
             [NotNull] IMemberTranslatorProvider memberTranslatorProvider,
             [NotNull] IMethodCallTranslatorProvider methodCallTranslatorProvider)
-            : base(dependencies, subquery: false)
+            : base(dependencies, queryCompilationContext, subquery: false)
         {
             _model = queryCompilationContext.Model;
             _sqlExpressionFactory = sqlExpressionFactory;
@@ -62,7 +62,7 @@ public class CosmosQueryableMethodTranslatingExpressionVisitor : QueryableMethod
         /// </summary>
         protected CosmosQueryableMethodTranslatingExpressionVisitor(
             [NotNull] CosmosQueryableMethodTranslatingExpressionVisitor parentVisitor)
-            : base(parentVisitor.Dependencies, subquery: true)
+            : base(parentVisitor.Dependencies, parentVisitor.QueryCompilationContext, subquery: true)
         {
             _model = parentVisitor._model;
             _sqlExpressionFactory = parentVisitor._sqlExpressionFactory;

src/EFCore.Cosmos/Query/Internal/CosmosShapedQueryCompilingExpressionVisitor.cs

@@ -67,7 +67,8 @@ protected override Expression VisitShapedQuery(ShapedQueryExpression shapedQuery
 
                     selectExpression.ApplyProjection();
 
-                    shaperBody = new CosmosProjectionBindingRemovingExpressionVisitor(selectExpression, jObjectParameter, IsTracking)
+                    shaperBody = new CosmosProjectionBindingRemovingExpressionVisitor(
+                        selectExpression, jObjectParameter, QueryCompilationContext.IsTracking)
                         .Visit(shaperBody);
 
                     var shaperLambda = Expression.Lambda(
@@ -90,8 +91,8 @@ protected override Expression VisitShapedQuery(ShapedQueryExpression shapedQuery
 
                 case ReadItemExpression readItemExpression:
 
-                    shaperBody =
-                        new CosmosProjectionBindingRemovingReadItemExpressionVisitor(readItemExpression, jObjectParameter, IsTracking)
+                    shaperBody = new CosmosProjectionBindingRemovingReadItemExpressionVisitor(
+                            readItemExpression, jObjectParameter, QueryCompilationContext.IsTracking)
                         .Visit(shaperBody);
 
                     var shaperReadItemLambda = Expression.Lambda(
@@ -108,7 +109,7 @@ protected override Expression VisitShapedQuery(ShapedQueryExpression shapedQuery
                         Expression.Constant(shaperReadItemLambda.Compile()),
                         Expression.Constant(_contextType),
                         Expression.Constant(_logger));
-                    
+
                 default:
                     throw new NotImplementedException();
             }

src/EFCore.Cosmos/Query/Internal/ReadItemExpression.cs

@@ -27,7 +27,7 @@ public class ReadItemExpression : Expression
         ///     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>
-        public override Type Type => typeof(JObject);
+        public override Type Type => typeof(object);
 
         /// <summary>
         ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
@@ -60,7 +60,7 @@ public class ReadItemExpression : Expression
         ///     doing so can result in application failures when updating to a new Entity Framework Core release.
         /// </summary>
         public virtual IEntityType EntityType { get; }
-        
+
         /// <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
@@ -83,7 +83,7 @@ public class ReadItemExpression : Expression
             Check.NotNull(propertyParameters, nameof(propertyParameters));
 
             Container = entityType.GetContainer();
-            
+
             ProjectionExpression = new ProjectionExpression(
                 new EntityProjectionExpression(
                     entityType,