From fb8230492f5a4d71da5b780aded91c9f1d915b3a Mon Sep 17 00:00:00 2001 From: Andriy Svyryd Date: Tue, 12 Dec 2023 10:18:03 -0800 Subject: [PATCH] Fix some API docs (#32594) --- .../StructuralTypeProjectionExpression.cs | 36 ++++++++++++------- src/EFCore/ChangeTracking/ChangeTracker.cs | 8 ++--- .../ChangeTracking/ObservableHashSet.cs | 19 +++++----- .../Diagnostics/DbContextLoggerOptions.cs | 22 +++++++----- .../BackingFieldAttributeConvention.cs | 16 +++++++-- .../DeleteBehaviorAttributeConvention.cs | 16 +++++++-- ...ityTypeConfigurationAttributeConvention.cs | 14 ++++++-- .../Conventions/KeyAttributeConvention.cs | 16 +++++++-- .../MaxLengthAttributeConvention.cs | 16 +++++++-- .../Conventions/OwnedAttributeConvention.cs | 14 ++++++-- .../PrecisionAttributeConvention.cs | 16 +++++++-- .../RequiredPropertyAttributeConvention.cs | 16 +++++++-- 12 files changed, 158 insertions(+), 51 deletions(-) diff --git a/src/EFCore.Relational/Query/StructuralTypeProjectionExpression.cs b/src/EFCore.Relational/Query/StructuralTypeProjectionExpression.cs index 828a7c95b2b..508054eb89f 100644 --- a/src/EFCore.Relational/Query/StructuralTypeProjectionExpression.cs +++ b/src/EFCore.Relational/Query/StructuralTypeProjectionExpression.cs @@ -66,26 +66,20 @@ private StructuralTypeProjectionExpression( public virtual ITypeBase StructuralType { get; } /// - /// TODO - /// - /// /// 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. - /// + /// [EntityFrameworkInternal] public virtual IReadOnlyDictionary TableMap { get; } /// - /// TODO - /// - /// /// 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. - /// + /// [EntityFrameworkInternal] public virtual bool IsNullable { get; } @@ -94,15 +88,30 @@ private StructuralTypeProjectionExpression( /// public virtual SqlExpression? DiscriminatorExpression { get; } - /// + /// + /// The of the . + /// public sealed override ExpressionType NodeType => ExpressionType.Extension; - /// + /// + /// The of the value represented by this . + /// public override Type Type => StructuralType.ClrType; - /// + /// + /// Reduces the node and then calls the method passing the reduced expression. + /// Throws an exception if the node isn't reducible. + /// + /// An instance of . + /// The expression being visited, or an expression which should replace it in the tree. + /// + /// Override this method to provide logic to walk the node's children. + /// A typical implementation will call visitor.Visit on each of its + /// children, and if any of them change, should return a new copy of + /// itself with the modified children. + /// protected override Expression VisitChildren(ExpressionVisitor visitor) { var changed = false; @@ -347,7 +356,10 @@ public virtual void AddNavigationBinding(INavigation navigation, StructuralTypeS : null; } - /// + /// + /// Creates a representation of the Expression. + /// + /// A representation of the Expression. public override string ToString() => $"EntityProjectionExpression: {StructuralType.ShortName()}"; } diff --git a/src/EFCore/ChangeTracking/ChangeTracker.cs b/src/EFCore/ChangeTracking/ChangeTracker.cs index 6b508916877..4f0a8134c8a 100644 --- a/src/EFCore/ChangeTracking/ChangeTracker.cs +++ b/src/EFCore/ChangeTracking/ChangeTracker.cs @@ -256,12 +256,10 @@ public virtual bool HasChanges() /// is usually called automatically by the context when up-to-date information is required (before /// and when returning change tracking information). You typically only need to /// call this method if you have disabled . - /// - /// - /// See EF Core change tracking for more information and examples. - /// - /// /// + /// + /// See EF Core change tracking for more information and examples. + /// public virtual void DetectChanges() { if (!_model.SkipDetectChanges) diff --git a/src/EFCore/ChangeTracking/ObservableHashSet.cs b/src/EFCore/ChangeTracking/ObservableHashSet.cs index a98fbed4278..cfd64a74045 100644 --- a/src/EFCore/ChangeTracking/ObservableHashSet.cs +++ b/src/EFCore/ChangeTracking/ObservableHashSet.cs @@ -8,13 +8,15 @@ namespace Microsoft.EntityFrameworkCore.ChangeTracking; /// -/// A hash set that implements the interfaces required for Entity Framework to use notification based change tracking -/// for a collection navigation property. +/// +/// A hash set that implements the interfaces required for Entity Framework to use notification based change tracking +/// for a collection navigation property. +/// +/// +/// See Local views of tracked entities in EF Core for more +/// information and examples. +/// /// -/// -/// See Local views of tracked entities in EF Core for more information and -/// examples. -/// /// The type of elements in the hash set. public class ObservableHashSet : ISet, IReadOnlyCollection, INotifyCollectionChanged, INotifyPropertyChanged, INotifyPropertyChanging @@ -113,8 +115,7 @@ public virtual void Clear() } /// - /// Determines whether the hash set object contains the - /// specified element. + /// Determines whether the hash set object contains the specified element. /// /// The element to locate in the hash set. /// @@ -362,7 +363,7 @@ public virtual bool IsProperSupersetOf(IEnumerable other) => _set.IsProperSupersetOf(other); /// - /// Determines whether the current System.Collections.Generic.HashSet`1 object and a specified collection share common elements. + /// Determines whether the current hash set object and a specified collection share common elements. /// /// The collection to compare to the current hash set. /// diff --git a/src/EFCore/Diagnostics/DbContextLoggerOptions.cs b/src/EFCore/Diagnostics/DbContextLoggerOptions.cs index 4a0eddca819..845d04de30d 100644 --- a/src/EFCore/Diagnostics/DbContextLoggerOptions.cs +++ b/src/EFCore/Diagnostics/DbContextLoggerOptions.cs @@ -52,19 +52,23 @@ public enum DbContextLoggerOptions LocalTime = 1 << 5, /// - /// The default used by . + /// + /// The default used by . + /// + /// + /// Includes , , , . + /// /// - /// - /// Includes , , , . - /// DefaultWithLocalTime = Level | Category | Id | LocalTime, /// - /// The same defaults as used by , - /// but with UTC timestamps. + /// + /// The same defaults as used by , + /// but with UTC timestamps. + /// + /// + /// Includes , , , . + /// /// - /// - /// Includes , , , . - /// DefaultWithUtcTime = Level | Category | Id | UtcTime } diff --git a/src/EFCore/Metadata/Conventions/BackingFieldAttributeConvention.cs b/src/EFCore/Metadata/Conventions/BackingFieldAttributeConvention.cs index edc5f62d605..f2f84f4893e 100644 --- a/src/EFCore/Metadata/Conventions/BackingFieldAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/BackingFieldAttributeConvention.cs @@ -24,7 +24,13 @@ public BackingFieldAttributeConvention(ProviderConventionSetBuilderDependencies { } - /// + /// + /// Called after a property is added to the entity type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionPropertyBuilder propertyBuilder, BackingFieldAttribute attribute, @@ -32,7 +38,13 @@ protected override void ProcessPropertyAdded( IConventionContext context) => propertyBuilder.HasField(attribute.Name, fromDataAnnotation: true); - /// + /// + /// Called after a complex property is added to a type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionComplexPropertyBuilder propertyBuilder, BackingFieldAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/DeleteBehaviorAttributeConvention.cs b/src/EFCore/Metadata/Conventions/DeleteBehaviorAttributeConvention.cs index 4185eb8b689..acf33765daf 100644 --- a/src/EFCore/Metadata/Conventions/DeleteBehaviorAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/DeleteBehaviorAttributeConvention.cs @@ -87,7 +87,13 @@ public virtual void ProcessModelFinalizing(IConventionModelBuilder modelBuilder, } } - /// + /// + /// Called after a property is added to the entity type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionPropertyBuilder propertyBuilder, DeleteBehaviorAttribute attribute, @@ -100,7 +106,13 @@ protected override void ProcessPropertyAdded( property.DeclaringType.DisplayName(), property.Name)); } - /// + /// + /// Called after a complex property is added to a type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionComplexPropertyBuilder propertyBuilder, DeleteBehaviorAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/EntityTypeConfigurationAttributeConvention.cs b/src/EFCore/Metadata/Conventions/EntityTypeConfigurationAttributeConvention.cs index bb5cdba4a1b..35aab0e75cc 100644 --- a/src/EFCore/Metadata/Conventions/EntityTypeConfigurationAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/EntityTypeConfigurationAttributeConvention.cs @@ -24,7 +24,12 @@ public EntityTypeConfigurationAttributeConvention(ProviderConventionSetBuilderDe { } - /// + /// + /// Called after an entity type is added to the model if it has an attribute. + /// + /// The builder for the entity type. + /// The attribute. + /// Additional information associated with convention execution. protected override void ProcessEntityTypeAdded( IConventionEntityTypeBuilder entityTypeBuilder, EntityTypeConfigurationAttribute attribute, @@ -46,7 +51,12 @@ protected override void ProcessEntityTypeAdded( .Invoke(null, new object[] { entityTypeBuilder.Metadata, entityTypeConfigurationType }); } - /// + /// + /// Called after an complex type is added to the model if it has an attribute. + /// + /// The builder for the complex type. + /// The attribute. + /// Additional information associated with convention execution. protected override void ProcessComplexTypeAdded( IConventionComplexTypeBuilder complexTypeBuilder, EntityTypeConfigurationAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/KeyAttributeConvention.cs b/src/EFCore/Metadata/Conventions/KeyAttributeConvention.cs index 56738f2b757..d8641075be5 100644 --- a/src/EFCore/Metadata/Conventions/KeyAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/KeyAttributeConvention.cs @@ -51,7 +51,13 @@ public virtual void ProcessEntityTypeBaseTypeChanged( CheckAttributesAndEnsurePrimaryKey((EntityType)entityTypeBuilder.Metadata, null, shouldThrow: false); } - /// + /// + /// Called after a property is added to the entity type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionPropertyBuilder propertyBuilder, KeyAttribute attribute, @@ -132,7 +138,13 @@ private bool CheckAttributesAndEnsurePrimaryKey( return primaryKeyAttributeExists; } - /// + /// + /// Called after a complex property is added to a type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionComplexPropertyBuilder propertyBuilder, KeyAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/MaxLengthAttributeConvention.cs b/src/EFCore/Metadata/Conventions/MaxLengthAttributeConvention.cs index 60ec1cf000c..52a5d88f125 100644 --- a/src/EFCore/Metadata/Conventions/MaxLengthAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/MaxLengthAttributeConvention.cs @@ -25,7 +25,13 @@ public MaxLengthAttributeConvention(ProviderConventionSetBuilderDependencies dep { } - /// + /// + /// Called after a property is added to the entity type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionPropertyBuilder propertyBuilder, MaxLengthAttribute attribute, @@ -38,7 +44,13 @@ protected override void ProcessPropertyAdded( } } - /// + /// + /// Called after a complex property is added to a type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionComplexPropertyBuilder propertyBuilder, MaxLengthAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/OwnedAttributeConvention.cs b/src/EFCore/Metadata/Conventions/OwnedAttributeConvention.cs index 4656f802741..4238477345d 100644 --- a/src/EFCore/Metadata/Conventions/OwnedAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/OwnedAttributeConvention.cs @@ -23,7 +23,12 @@ public OwnedAttributeConvention(ProviderConventionSetBuilderDependencies depende { } - /// + /// + /// Called after an entity type is added to the model if it has an attribute. + /// + /// The builder for the entity type. + /// The attribute. + /// Additional information associated with convention execution. protected override void ProcessEntityTypeAdded( IConventionEntityTypeBuilder entityTypeBuilder, OwnedAttribute attribute, @@ -36,7 +41,12 @@ protected override void ProcessEntityTypeAdded( } } - /// + /// + /// Called after an complex type is added to the model if it has an attribute. + /// + /// The builder for the complex type. + /// The attribute. + /// Additional information associated with convention execution. protected override void ProcessComplexTypeAdded( IConventionComplexTypeBuilder complexTypeBuilder, OwnedAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/PrecisionAttributeConvention.cs b/src/EFCore/Metadata/Conventions/PrecisionAttributeConvention.cs index 9d1f701823f..9f6dbb7f029 100644 --- a/src/EFCore/Metadata/Conventions/PrecisionAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/PrecisionAttributeConvention.cs @@ -23,7 +23,13 @@ public PrecisionAttributeConvention(ProviderConventionSetBuilderDependencies dep { } - /// + /// + /// Called after a property is added to the entity type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionPropertyBuilder propertyBuilder, PrecisionAttribute attribute, @@ -38,7 +44,13 @@ protected override void ProcessPropertyAdded( } } - /// + /// + /// Called after a complex property is added to a type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionComplexPropertyBuilder propertyBuilder, PrecisionAttribute attribute, diff --git a/src/EFCore/Metadata/Conventions/RequiredPropertyAttributeConvention.cs b/src/EFCore/Metadata/Conventions/RequiredPropertyAttributeConvention.cs index 0fca17b54ce..3ce1751cdda 100644 --- a/src/EFCore/Metadata/Conventions/RequiredPropertyAttributeConvention.cs +++ b/src/EFCore/Metadata/Conventions/RequiredPropertyAttributeConvention.cs @@ -24,7 +24,13 @@ public RequiredPropertyAttributeConvention(ProviderConventionSetBuilderDependenc { } - /// + /// + /// Called after a property is added to the entity type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionPropertyBuilder propertyBuilder, RequiredAttribute attribute, @@ -32,7 +38,13 @@ protected override void ProcessPropertyAdded( IConventionContext context) => propertyBuilder.IsRequired(true, fromDataAnnotation: true); - /// + /// + /// Called after a complex property is added to a type with an attribute on the associated CLR property or field. + /// + /// The builder for the property. + /// The attribute. + /// The member that has the attribute. + /// Additional information associated with convention execution. protected override void ProcessPropertyAdded( IConventionComplexPropertyBuilder propertyBuilder, RequiredAttribute attribute,