Add query documentation in EF Core

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 void ExecutingSqlQuery(
                 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 WithExecutionStrategyFactory(
         /// </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 CosmosQueryTranslationPreprocessor(
             _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 CosmosQueryableMethodTranslatingExpressionVisitor(
             [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 CosmosQueryableMethodTranslatingExpressionVisitor(
         /// </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 ReadItemExpression(
             Check.NotNull(propertyParameters, nameof(propertyParameters));
 
             Container = entityType.GetContainer();
-            
+
             ProjectionExpression = new ProjectionExpression(
                 new EntityProjectionExpression(
                     entityType,