.Net: Improve docs for VectorData.Abstractions

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/CollectionJsonModelBuilder.cs

@@ -10,8 +10,8 @@
 namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
-/// A model builder that performs logic specific to connectors which use System.Text.Json for serialization.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// Represents a model builder that performs logic specific to connectors that use System.Text.Json for serialization.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public abstract class CollectionJsonModelBuilder : CollectionModelBuilder
@@ -27,7 +27,7 @@ protected CollectionJsonModelBuilder(CollectionModelBuildingOptions options)
     }
 
     /// <summary>
-    /// Builds and returns an <see cref="CollectionModel"/> from the given <paramref name="type"/> and <paramref name="definition"/>.
+    /// Builds and returns a <see cref="CollectionModel"/> from the given <paramref name="type"/> and <paramref name="definition"/>.
     /// </summary>
     [RequiresDynamicCode("This model building variant is not compatible with NativeAOT. See BuildDynamic() for dynamic mapping, and a third variant accepting source-generated delegates will be introduced in the future.")]
     [RequiresUnreferencedCode("This model building variant is not compatible with trimming. See BuildDynamic() for dynamic mapping, and a third variant accepting source-generated delegates will be introduced in the future.")]
@@ -43,7 +43,7 @@ public virtual CollectionModel Build(
     }
 
     /// <summary>
-    /// Builds and returns an <see cref="CollectionModel"/> for dynamic mapping scenarios from the given <paramref name="definition"/>.
+    /// Builds and returns a <see cref="CollectionModel"/> for dynamic mapping scenarios from the given <paramref name="definition"/>.
     /// </summary>
     public virtual CollectionModel BuildDynamic(
         VectorStoreCollectionDefinition definition,

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/CollectionModel.cs

@@ -12,8 +12,8 @@
 namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
-/// A model representing a record in a vector store collection.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// Represents a record in a vector store collection.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public sealed class CollectionModel
@@ -26,32 +26,32 @@ public sealed class CollectionModel
     private DataPropertyModel? _singleFullTextSearchProperty;
 
     /// <summary>
-    /// The key properties of the record.
+    /// Gets the key properties of the record.
     /// </summary>
     public IReadOnlyList<KeyPropertyModel> KeyProperties { get; }
 
     /// <summary>
-    /// The data properties of the record.
+    /// Gets the data properties of the record.
     /// </summary>
     public IReadOnlyList<DataPropertyModel> DataProperties { get; }
 
     /// <summary>
-    /// The vector properties of the record.
+    /// Gets the vector properties of the record.
     /// </summary>
     public IReadOnlyList<VectorPropertyModel> VectorProperties { get; }
 
     /// <summary>
-    /// All properties of the record, of all types.
+    /// Gets all properties of the record, of all types.
     /// </summary>
     public IReadOnlyList<PropertyModel> Properties { get; }
 
     /// <summary>
-    /// All properties of the record, of all types, indexed by their model name.
+    /// Gets all properties of the record, of all types, indexed by their model name.
     /// </summary>
     public IReadOnlyDictionary<string, PropertyModel> PropertyMap { get; }
 
     /// <summary>
-    /// Whether any of the vector properties in the model require embedding generation.
+    /// Gets a value that indicates whether any of the vector properties in the model require embedding generation.
     /// </summary>
     public bool EmbeddingGenerationRequired { get; }
 
@@ -102,12 +102,11 @@ public TRecord CreateRecord<TRecord>()
     }
 
     /// <summary>
-    /// Get the vector property with the provided name if a name is provided, and fall back
-    /// to a vector property in the schema if not. If no name is provided and there is more
-    /// than one vector property, an exception will be thrown.
+    /// Gets the vector property with the provided name if a name is provided, and falls back
+    /// to a vector property in the schema if not.
     /// </summary>
-    /// <param name="searchOptions">The search options.</param>
-    /// <exception cref="InvalidOperationException">Thrown if the provided property name is not a valid vector property name.</exception>
+    /// <param name="searchOptions">The search options, which defines the vector property name.</param>
+    /// <exception cref="InvalidOperationException"><para>The provided property name is not a valid text data property name.</para><para>OR</para><para>No name was provided and there's more than one vector property.</para></exception>
     public VectorPropertyModel GetVectorPropertyOrSingle<TRecord>(VectorSearchOptions<TRecord> searchOptions)
     {
         if (searchOptions.VectorProperty is not null)
@@ -137,12 +136,11 @@ public VectorPropertyModel GetVectorPropertyOrSingle<TRecord>(VectorSearchOption
     }
 
     /// <summary>
-    /// Get the text data property, that has full text search indexing enabled, with the provided name if a name is provided, and fall back
-    /// to a text data property in the schema if not. If no name is provided and there is more than one text data property with
-    /// full text search indexing enabled, an exception will be thrown.
+    /// Gets the text data property with the provided name that has full text search indexing enabled, or falls back
+    /// to a text data property in the schema if no name is provided.
     /// </summary>
     /// <param name="expression">The full text search property selector.</param>
-    /// <exception cref="InvalidOperationException">Thrown if the provided property name is not a valid text data property name.</exception>
+    /// <exception cref="InvalidOperationException"><para>The provided property name is not a valid text data property name.</para><para>OR</para><para>No name was provided and there's more than one text data property with full text search indexing enabled.</para></exception>
     public DataPropertyModel GetFullTextDataPropertyOrSingle<TRecord>(Expression<Func<TRecord, object?>>? expression)
     {
         if (expression is not null)
@@ -183,10 +181,10 @@ public DataPropertyModel GetFullTextDataPropertyOrSingle<TRecord>(Expression<Fun
     }
 
     /// <summary>
-    /// Get the data or key property selected by provided expression.
+    /// Gets the data or key property selected by the provided expression.
     /// </summary>
     /// <param name="expression">The property selector.</param>
-    /// <exception cref="InvalidOperationException">Thrown if the provided property name is not a valid data or key property name.</exception>
+    /// <exception cref="InvalidOperationException">The provided property name is not a valid data or key property name.</exception>
     public PropertyModel GetDataOrKeyProperty<TRecord>(Expression<Func<TRecord, object?>> expression)
         => this.GetMatchingProperty<TRecord, PropertyModel>(expression, data: true);
 

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/CollectionModelBuilder.cs

@@ -12,44 +12,44 @@ namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
 /// Represents a builder for a <see cref="CollectionModel"/>.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
-/// <remarks>Note that this class is single-use only, and not thread-safe.</remarks>
+/// <remarks>This class is single-use only, and not thread-safe.</remarks>
 [Experimental("MEVD9001")]
 public abstract class CollectionModelBuilder
 {
     /// <summary>
-    /// Options for building the model.
+    /// Gets the options for building the model.
     /// </summary>
     protected CollectionModelBuildingOptions Options { get; }
 
     /// <summary>
-    /// The key properties of the record.
+    /// Gets the key properties of the record.
     /// </summary>
     protected List<KeyPropertyModel> KeyProperties { get; } = [];
 
     /// <summary>
-    /// The data properties of the record.
+    /// Gets the data properties of the record.
     /// </summary>
     protected List<DataPropertyModel> DataProperties { get; } = [];
 
     /// <summary>
-    /// The vector properties of the record.
+    /// Gets the vector properties of the record.
     /// </summary>
     protected List<VectorPropertyModel> VectorProperties { get; } = [];
 
     /// <summary>
-    /// All properties of the record, of all types.
+    /// Gets all properties of the record, of all types.
     /// </summary>
     protected IEnumerable<PropertyModel> Properties => this.PropertyMap.Values;
 
     /// <summary>
-    /// All properties of the record, of all types, indexed by their model name.
+    /// Gets all properties of the record, of all types, indexed by their model name.
     /// </summary>
     protected Dictionary<string, PropertyModel> PropertyMap { get; } = new();
 
     /// <summary>
-    /// The default embedding generator to use for vector properties, when none is specified at the property or collection level.
+    /// Gets the default embedding generator to use for vector properties, when none is specified at the property or collection level.
     /// </summary>
     protected IEmbeddingGenerator? DefaultEmbeddingGenerator { get; private set; }
 
@@ -245,7 +245,7 @@ protected virtual void ProcessTypeProperties(Type type, VectorStoreCollectionDef
     }
 
     /// <summary>
-    /// As part of building the model, this method processes the given <paramref name="definition"/>.
+    /// Processes the given <paramref name="definition"/> as part of building the model.
     /// </summary>
     protected virtual void ProcessRecordDefinition(VectorStoreCollectionDefinition definition, Type? type)
     {

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/CollectionModelBuildingOptions.cs

@@ -6,34 +6,34 @@ namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
 /// Contains options affecting model building; passed to <see cref="CollectionModelBuilder"/>.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public sealed class CollectionModelBuildingOptions
 {
     /// <summary>
-    /// Whether multiple key properties are supported.
+    /// Gets a value that indicates whether multiple key properties are supported.
     /// </summary>
     public required bool SupportsMultipleKeys { get; init; }
 
     /// <summary>
-    /// Whether multiple vector properties are supported.
+    /// Gets a value that indicates whether multiple vector properties are supported.
     /// </summary>
     public required bool SupportsMultipleVectors { get; init; }
 
     /// <summary>
-    /// Whether at least one vector property is required.
+    /// Gets a value that indicates whether at least one vector property is required.
     /// </summary>
     public required bool RequiresAtLeastOneVector { get; init; }
 
     /// <summary>
-    /// Indicates that an external serializer will be used (e.g. System.Text.Json).
+    /// Gets a value that indicates whether an external serializer will be used (for example, System.Text.Json).
     /// </summary>
     public bool UsesExternalSerializer { get; init; }
 
     /// <summary>
-    /// Indicates that the database requires the key property to have a special, reserved name.
-    /// When set, the model builder will manage the key storage name, and users may not customize it.
+    /// Gets the special, reserved name for the key property of the database.
+    /// When set, the model builder manages the key storage name, and users cannot customize it.
     /// </summary>
     public string? ReservedKeyStorageName { get; init; }
 }

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/DataPropertyModel.cs

@@ -7,7 +7,7 @@ namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
 /// Represents a data property on a vector store record.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public class DataPropertyModel(string modelName, Type type) : PropertyModel(modelName, type)

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/Filter/FilterTranslationPreprocessor.cs

@@ -10,7 +10,7 @@ namespace Microsoft.Extensions.VectorData.ProviderServices.Filter;
 
 /// <summary>
 /// A processor for user-provided filter expressions which performs various common transformations before actual translation takes place.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public class FilterTranslationPreprocessor : ExpressionVisitor

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/KeyPropertyModel.cs

@@ -7,7 +7,7 @@ namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
 /// Represents a key property on a vector store record.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public class KeyPropertyModel(string modelName, Type type) : PropertyModel(modelName, type)

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/PropertyModel.cs

@@ -10,20 +10,20 @@ namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
 /// Represents a property on a vector store record.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public abstract class PropertyModel(string modelName, Type type)
 {
     private string? _storageName;
 
     /// <summary>
-    /// The model name of the property. If the property corresponds to a .NET property, this name is the name of that property.
+    /// Gets or sets the model name of the property. If the property corresponds to a .NET property, this name is the name of that property.
     /// </summary>
     public string ModelName { get; set; } = modelName;
 
     /// <summary>
-    /// The storage name of the property. This is the name to which the property is mapped in the vector store.
+    /// Gets or sets the storage name of the property. This is the name to which the property is mapped in the vector store.
     /// </summary>
     public string StorageName
     {
@@ -35,20 +35,23 @@ public string StorageName
     // TODO: Spend more time thinking about this, there may be a less hacky way to handle it.
 
     /// <summary>
-    /// A temporary storage name for the property, for use during the serialization process by certain connectors.
+    /// Gets or sets the temporary storage name for the property, for use during the serialization process by certain connectors.
     /// </summary>
     [Experimental("MEVD9001")]
     public string? TemporaryStorageName { get; set; }
 
     /// <summary>
-    /// The CLR type of the property.
+    /// Gets or sets the CLR type of the property.
     /// </summary>
     public Type Type { get; set; } = type;
 
     /// <summary>
+    /// Gets or sets the reflection <see cref="PropertyInfo"/> for the .NET property.
+    /// </summary>
+    /// <value>
     /// The reflection <see cref="PropertyInfo"/> for the .NET property.
     /// <see langword="null"/> when using dynamic mapping.
-    /// </summary>
+    /// </value>
     public PropertyInfo? PropertyInfo { get; set; }
 
     /// <summary>

dotnet/src/Connectors/VectorData.Abstractions/ProviderServices/VectorPropertyModel.cs

@@ -13,15 +13,15 @@ namespace Microsoft.Extensions.VectorData.ProviderServices;
 
 /// <summary>
 /// Represents a vector property on a vector store record.
-/// This is an internal support type meant for use by connectors only, and not for use by applications.
+/// This is an internal support type meant for use by connectors only and not by applications.
 /// </summary>
 [Experimental("MEVD9001")]
 public class VectorPropertyModel(string modelName, Type type) : PropertyModel(modelName, type)
 {
     private int _dimensions;
 
     /// <summary>
-    /// The number of dimensions that the vector has.
+    /// Gets or sets the number of dimensions that the vector has.
     /// </summary>
     /// <remarks>
     /// This property is required when creating collections, but can be omitted if not using that functionality.
@@ -43,25 +43,25 @@ public int Dimensions
     }
 
     /// <summary>
-    /// The kind of index to use.
+    /// Gets or sets the kind of index to use.
     /// </summary>
     /// <value>
-    /// The default varies by database type. See the documentation of your chosen database connector for more information.
+    /// The default varies by database type. For more information, see the documentation of your chosen database connector.
     /// </value>
     /// <seealso cref="Microsoft.Extensions.VectorData.IndexKind"/>
     public string? IndexKind { get; set; }
 
     /// <summary>
-    /// The distance function to use when comparing vectors.
+    /// Gets or sets the distance function to use when comparing vectors.
     /// </summary>
     /// <value>
-    /// The default varies by database type. See the documentation of your chosen database connector for more information.
+    /// The default varies by database type. For more information, see the documentation of your chosen database connector.
     /// </value>
     /// <seealso cref="Microsoft.Extensions.VectorData.DistanceFunction"/>
     public string? DistanceFunction { get; set; }
 
     /// <summary>
-    /// If <see cref="EmbeddingGenerator"/> is set, contains the type representing the embedding stored in the database.
+    /// Gets or sets the type representing the embedding stored in the database if <see cref="EmbeddingGenerator"/> is set.
     /// Otherwise, this property is identical to <see cref="Type"/>.
     /// </summary>
     // TODO: sort out the nullability story here: EmbeddingType must be non-null after model building is complete, but can be null during
@@ -70,7 +70,7 @@ public int Dimensions
     public Type EmbeddingType { get; set; } = null!;
 
     /// <summary>
-    /// The embedding generator to use for this property.
+    /// Gets or sets the embedding generator to use for this property.
     /// </summary>
     public IEmbeddingGenerator? EmbeddingGenerator { get; set; }
 

dotnet/src/Connectors/VectorData.Abstractions/RecordAttributes/VectorStoreVectorAttribute.cs

@@ -37,7 +37,7 @@ public VectorStoreVectorAttribute(int Dimensions)
     public int Dimensions { get; private set; }
 
     /// <summary>
-    /// Gets the kind of index to use.
+    /// Gets or sets the kind of index to use.
     /// </summary>
     /// <value>
     /// The default value varies by database type. See the documentation of your chosen database connector for more information.
@@ -48,7 +48,7 @@ public VectorStoreVectorAttribute(int Dimensions)
 #pragma warning restore CA1019
 
     /// <summary>
-    /// Gets the distance function to use when comparing vectors.
+    /// Gets or sets the distance function to use when comparing vectors.
     /// </summary>
     /// <value>
     /// The default value varies by database type. See the documentation of your chosen database connector for more information.