chore: Added remaining XML comments

Shazwazza · Jun 18, 2023 · 2f9548a · 2f9548a
1 parent 1cb285e
commit 2f9548a
Show file tree

Hide file tree

Showing 23 changed files with 141 additions and 65 deletions.
diff --git a/src/Examine.Core/BaseIndexProvider.cs b/src/Examine.Core/BaseIndexProvider.cs
@@ -6,7 +6,6 @@
 
 namespace Examine
 {
-    /// <inheritdoc />
     /// <summary>
     /// Base class for an Examine Index Provider
     /// </summary>
@@ -34,14 +33,11 @@ protected BaseIndexProvider(ILoggerFactory loggerFactory, string name,
         }
 
         /// <summary>
-        /// Represents a type used to configure the logging system and create instances of
-        /// <see cref="ILogger"/> from the registered Microsoft.Extensions.Logging.ILoggerProviders.
+        /// The factory used to create instances of <see cref="ILogger"/>.
         /// </summary>
         protected ILoggerFactory LoggerFactory { get; }
 
-        /// <summary>
-        /// The index name
-        /// </summary>
+        /// <inheritdoc/>
         public virtual string Name { get; }
 
         /// <summary>
@@ -81,14 +77,11 @@ protected abstract void PerformDeleteFromIndex(IEnumerable<string> itemIds,
 
         #region IIndex members
 
-        /// <summary>
-        /// The default searcher of the index
-        /// </summary>
+        /// <inheritdoc/>
         public abstract ISearcher Searcher { get; }
 
-        /// <inheritdoc />
         /// <summary>
-        /// Validates the items and calls <see cref="M:Examine.Providers.BaseIndexProvider.PerformIndexItems(System.Collections.Generic.IEnumerable{Examine.ValueSet})" />
+        /// Validates the items and calls <see cref="PerformIndexItems(IEnumerable{ValueSet}, Action{IndexOperationEventArgs})"/>
         /// </summary>
         /// <param name="values"></param>
         public void IndexItems(IEnumerable<ValueSet> values)
@@ -102,21 +95,14 @@ public void IndexItems(IEnumerable<ValueSet> values)
         public void DeleteFromIndex(IEnumerable<string> itemIds)
             => PerformDeleteFromIndex(itemIds, OnIndexOperationComplete);
 
-        /// <summary>
-        /// Creates a new index, any existing index will be deleted
-        /// </summary>
+        /// <inheritdoc/>
         public abstract void CreateIndex();
 
-        /// <summary>
-        /// Returns the mappings for field types to index field types
-        /// </summary>
+        /// <inheritdoc/>
         public ReadOnlyFieldDefinitionCollection FieldDefinitions =>
             _indexOptions.FieldDefinitions ?? new FieldDefinitionCollection();
 
-        /// <summary>
-        /// Check if the index exists
-        /// </summary>
-        /// <returns></returns>
+        /// <inheritdoc/>
         public abstract bool IndexExists();
 
         #endregion
@@ -143,17 +129,17 @@ public void DeleteFromIndex(IEnumerable<string> itemIds)
         protected void OnIndexOperationComplete(IndexOperationEventArgs e) => IndexOperationComplete?.Invoke(this, e);
 
         /// <summary>
-        /// Raises the <see cref="E:IndexingError"/> event.
+        /// Raises the <see cref="IndexingError"/> event.
         /// </summary>
-        /// <param name="e">The <see cref="Examine.IndexingErrorEventArgs"/> instance containing the event data.</param>
+        /// <param name="e">The <see cref="IndexingErrorEventArgs"/> instance containing the event data.</param>
         protected virtual void OnIndexingError(IndexingErrorEventArgs e)
         {
             _logger.LogError(e.Exception, e.Message);
             IndexingError?.Invoke(this, e);
         }
 
         /// <summary>
-        /// Raises the <see cref="E:TransformingIndexValues"/> event.
+        /// Raises the <see cref="TransformingIndexValues"/> event.
         /// </summary>
         /// <param name="e">The <see cref="IndexingItemEventArgs"/> instance containing the event data.</param>
         protected virtual void OnTransformingIndexValues(IndexingItemEventArgs e) =>

diff --git a/src/Examine.Core/BaseSearchProvider.cs b/src/Examine.Core/BaseSearchProvider.cs
@@ -18,12 +18,7 @@ protected BaseSearchProvider(string name)
         /// <inheritdoc/>
         public string Name { get; }
 
-        /// <summary>
-        /// Searches the index
-        /// </summary>
-        /// <param name="searchText"></param>
-        /// <param name="options"></param>
-        /// <returns></returns>
+        /// <inheritdoc/>
         public abstract ISearchResults Search(string searchText, QueryOptions options = null);
 
         /// <inheritdoc />

diff --git a/src/Examine.Core/FieldDefinitionCollection.cs b/src/Examine.Core/FieldDefinitionCollection.cs
@@ -16,7 +16,7 @@ public FieldDefinitionCollection()
         }
 
         /// <summary>
-        /// Adds a key/value pair to the System.Collections.Concurrent.ConcurrentDictionary`2
+        /// Adds a key/value pair to the <see cref="System.Collections.Concurrent.ConcurrentDictionary{TKey, TValue}"/>
         /// by using the specified function if the key does not already exist, or returns
         /// the existing value if the key exists.
         /// </summary>
@@ -34,11 +34,11 @@ public FieldDefinitionCollection()
         public void AddOrUpdate(FieldDefinition definition) => Definitions.AddOrUpdate(definition.Name, definition, (s, factory) => definition);
 
         /// <summary>
-        /// Attempts to add the specified key and value to the System.Collections.Concurrent.ConcurrentDictionary`2.
+        /// Attempts to add the specified key and value to the <see cref="System.Collections.Concurrent.ConcurrentDictionary{TKey, TValue}"/>.
         /// </summary>
         /// <param name="definition"></param>
         /// <returns>
-        /// True if the key/value pair was added to the System.Collections.Concurrent.ConcurrentDictionary`2
+        /// True if the key/value pair was added to the <see cref="System.Collections.Concurrent.ConcurrentDictionary{TKey, TValue}"/>
         /// successfully; false if the key already exists.
         /// </returns>
         /// <exception cref="ArgumentNullException">definition.Name is null</exception>

diff --git a/src/Examine.Core/Search/FacetResult.cs b/src/Examine.Core/Search/FacetResult.cs
@@ -37,6 +37,7 @@ public IFacetValue Facet(string label)
             return _dictValues[label];
         }
 
+        /// <inheritdoc/>
         public bool TryGetFacet(string label, out IFacetValue facetValue)
         {
             SetValuesDictionary();

diff --git a/src/Examine.Core/Search/IFacetResult.cs b/src/Examine.Core/Search/IFacetResult.cs
@@ -13,5 +13,13 @@ public interface IFacetResult : IEnumerable<IFacetValue>
         /// <param name="label"></param>
         /// <returns></returns>
         IFacetValue Facet(string label);
+
+        /// <summary>
+        /// Trys to get a facet value for a label
+        /// </summary>
+        /// <param name="label"></param>
+        /// <param name="facetValue"></param>
+        /// <returns></returns>
+        bool TryGetFacet(string label, out IFacetValue facetValue);
     }
 }
diff --git a/src/Examine.Core/Search/OrderingExtensions.cs b/src/Examine.Core/Search/OrderingExtensions.cs
@@ -1,12 +1,16 @@
-using System;
+using System;
 
 namespace Examine.Search
 {
+    /// <summary>
+    /// Extensions on the <see cref="IOrdering"/> interface
+    /// </summary>
     public static class OrderingExtensions
     {
         /// <summary>
         /// Allows for selecting facets to return in your query
         /// </summary>
+        /// <param name="ordering"></param>
         /// <param name="facets"></param>
         /// <returns></returns>
         public static IQueryExecutor WithFacets(this IOrdering ordering, Action<IFacetOperations> facets)

diff --git a/src/Examine.Lucene/Indexing/DateTimeType.cs b/src/Examine.Lucene/Indexing/DateTimeType.cs
@@ -88,6 +88,7 @@ public override Query GetQuery(DateTime? lower, DateTime? upper, bool lowerInclu
                 upper != null ? DateToLong(upper.Value) : (long?)null, lowerInclusive, upperInclusive);
         }
 
+        /// <inheritdoc/>
         public virtual IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field)
             => field.ExtractFacets(facetExtractionContext);
     }

diff --git a/src/Examine.Lucene/Indexing/DoubleType.cs b/src/Examine.Lucene/Indexing/DoubleType.cs
@@ -64,6 +64,8 @@ public override Query GetQuery(double? lower, double? upper, bool lowerInclusive
                 lower ?? double.MinValue,
                 upper ?? double.MaxValue, lowerInclusive, upperInclusive);
         }
+
+        /// <inheritdoc/>
         public virtual IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field)
             => field.ExtractFacets(facetExtractionContext);
     }

diff --git a/src/Examine.Lucene/Indexing/FullTextType.cs b/src/Examine.Lucene/Indexing/FullTextType.cs
@@ -34,10 +34,12 @@ public class FullTextType : IndexFieldValueTypeBase, IIndexFacetValueType
         /// Constructor
         /// </summary>
         /// <param name="fieldName"></param>
+        /// <param name="logger"></param>
+        /// <param name="sortable"></param>
+        /// <param name="isFacetable"></param>
         /// <param name="analyzer">
         /// Defaults to <see cref="CultureInvariantStandardAnalyzer"/>
         /// </param>
-        /// <param name="sortable"></param>
         public FullTextType(string fieldName, ILoggerFactory logger, bool sortable = false, bool isFacetable = false, Analyzer analyzer = null)
             : base(fieldName, logger, true)
         {
@@ -178,6 +180,7 @@ public override Query GetQuery(string query)
             return GenerateQuery(FieldName, query, _analyzer);
         }
 
+        /// <inheritdoc/>
         public virtual IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field)
             => field.ExtractFacets(facetExtractionContext);
     }

diff --git a/src/Examine.Lucene/Indexing/IIndexFacetValueType.cs b/src/Examine.Lucene/Indexing/IIndexFacetValueType.cs
@@ -4,13 +4,15 @@
 
 namespace Examine.Lucene.Indexing
 {
+    /// <summary>
+    /// Represents a facet index value type
+    /// </summary>
     public interface IIndexFacetValueType
     {
         /// <summary>
         /// Extracts the facets from the field
         /// </summary>
-        /// <param name="facetsCollector"></param>
-        /// <param name="sortedSetReaderState"></param>
+        /// <param name="facetExtractionContext"></param>
         /// <param name="field"></param>
         /// <returns>A dictionary of facets for this field</returns>
         IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field);

diff --git a/src/Examine.Lucene/Indexing/Int32Type.cs b/src/Examine.Lucene/Indexing/Int32Type.cs
@@ -65,6 +65,7 @@ public override Query GetQuery(int? lower, int? upper, bool lowerInclusive = tru
                 upper, lowerInclusive, upperInclusive);
         }
 
+        /// <inheritdoc/>
         public virtual IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field)
             => field.ExtractFacets(facetExtractionContext);
     }

diff --git a/src/Examine.Lucene/Indexing/Int64Type.cs b/src/Examine.Lucene/Indexing/Int64Type.cs
@@ -64,6 +64,8 @@ public override Query GetQuery(long? lower, long? upper, bool lowerInclusive = t
                 lower,
                 upper, lowerInclusive, upperInclusive);
         }
+
+        /// <inheritdoc/>
         public virtual IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field)
             => field.ExtractFacets(facetExtractionContext);
     }

diff --git a/src/Examine.Lucene/Indexing/SingleType.cs b/src/Examine.Lucene/Indexing/SingleType.cs
@@ -65,6 +65,7 @@ public override Query GetQuery(float? lower, float? upper, bool lowerInclusive =
                 upper ?? float.MaxValue, lowerInclusive, upperInclusive);
         }
 
+        /// <inheritdoc/>
         public virtual IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext, IFacetField field)
             => field.ExtractFacets(facetExtractionContext);
     }

diff --git a/src/Examine.Lucene/Providers/BaseLuceneSearcher.cs b/src/Examine.Lucene/Providers/BaseLuceneSearcher.cs
@@ -19,6 +19,7 @@ public abstract class BaseLuceneSearcher : BaseSearchProvider
         /// </summary>
         /// <param name="name"></param>
         /// <param name="analyzer"></param>
+        /// <param name="facetsConfig"></param>
         protected BaseLuceneSearcher(string name, Analyzer analyzer, FacetsConfig facetsConfig)
             : base(name)
         {

diff --git a/src/Examine.Lucene/Providers/LuceneSearcher.cs b/src/Examine.Lucene/Providers/LuceneSearcher.cs
@@ -23,6 +23,7 @@ public class LuceneSearcher : BaseLuceneSearcher, IDisposable
         /// <param name="searcherManager"></param>
         /// <param name="analyzer"></param>
         /// <param name="fieldValueTypeCollection"></param>
+        /// <param name="facetsConfig"></param>
         public LuceneSearcher(string name, SearcherManager searcherManager, Analyzer analyzer, FieldValueTypeCollection fieldValueTypeCollection, FacetsConfig facetsConfig)
             : base(name, analyzer, facetsConfig)
         {

diff --git a/src/Examine.Lucene/Search/FacetDoubleField.cs b/src/Examine.Lucene/Search/FacetDoubleField.cs
@@ -5,15 +5,26 @@
 
 namespace Examine.Lucene.Search
 {
+    /// <summary>
+    /// Represents a double facet field
+    /// </summary>
     public readonly struct FacetDoubleField : IFacetField
     {
+        /// <summary>
+        /// The double ranges for the field
+        /// </summary>
         public Examine.Search.DoubleRange[] DoubleRanges { get; }
 
+        /// <inheritdoc/>
         public string Field { get; }
 
+        /// <inheritdoc/>
         public string FacetField { get; }
+
+        /// <inheritdoc/>
         public bool IsTaxonomyIndexed { get; }
 
+        /// <inheritdoc/>
         public FacetDoubleField(string field, Examine.Search.DoubleRange[] doubleRanges, string facetField, bool isTaxonomyIndexed = false)
         {
             Field = field;
@@ -22,6 +33,7 @@ public FacetDoubleField(string field, Examine.Search.DoubleRange[] doubleRanges,
             IsTaxonomyIndexed = isTaxonomyIndexed;
         }
 
+        /// <inheritdoc/>
         public IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext)
         {
             var doubleFacetCounts = new DoubleRangeFacetCounts(Field, facetExtractionContext.FacetsCollector, DoubleRanges.AsLuceneRange().ToArray());

diff --git a/src/Examine.Lucene/Search/FacetFloatField.cs b/src/Examine.Lucene/Search/FacetFloatField.cs
@@ -6,15 +6,26 @@
 
 namespace Examine.Lucene.Search
 {
+    /// <summary>
+    /// Represents a float facet field
+    /// </summary>
     public readonly struct FacetFloatField : IFacetField
     {
+        /// <summary>
+        /// The float ranges for the field
+        /// </summary>
         public FloatRange[] FloatRanges { get; }
 
+        /// <inheritdoc/>
         public string Field { get; }
 
+        /// <inheritdoc/>
         public string FacetField { get; }
+
+        /// <inheritdoc/>
         public bool IsTaxonomyIndexed { get; }
 
+        /// <inheritdoc/>
         public FacetFloatField(string field, FloatRange[] floatRanges, string facetField, bool isTaxonomyIndexed = false)
         {
             Field = field;
@@ -23,6 +34,7 @@ public FacetFloatField(string field, FloatRange[] floatRanges, string facetField
             IsTaxonomyIndexed = isTaxonomyIndexed;
         }
 
+        /// <inheritdoc/>
         public IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext)
         {
             var floatFacetCounts = new DoubleRangeFacetCounts(Field, new SingleFieldSource(Field), facetExtractionContext.FacetsCollector, FloatRanges.AsLuceneRange().ToArray());

diff --git a/src/Examine.Lucene/Search/FacetFullTextField.cs b/src/Examine.Lucene/Search/FacetFullTextField.cs
@@ -5,20 +5,36 @@
 
 namespace Examine.Lucene.Search
 {
+    /// <summary>
+    /// Represents a full text facet field
+    /// </summary>
     public class FacetFullTextField : IFacetField
     {
+        /// <summary>
+        /// Maximum number of terms to return
+        /// </summary>
         public int MaxCount { get; internal set; }
 
+        /// <summary>
+        /// Filter values
+        /// </summary>
         public string[] Values { get; }
 
+        /// <inheritdoc/>
         public string Field { get; }
 
+        /// <inheritdoc/>
         public string FacetField { get; }
 
+        /// <summary>
+        /// Path hierachy
+        /// </summary>
         public string[] Path { get; internal set; }
 
+        /// <inheritdoc/>
         public bool IsTaxonomyIndexed { get; }
 
+        /// <inheritdoc/>
         public FacetFullTextField(string field, string[] values, string facetField, int maxCount = 10, string[] path = null, bool isTaxonomyIndexed = false)
         {
             Field = field;
@@ -29,6 +45,7 @@ public FacetFullTextField(string field, string[] values, string facetField, int
             IsTaxonomyIndexed = isTaxonomyIndexed;
         }
 
+        /// <inheritdoc/>
         public IEnumerable<KeyValuePair<string, IFacetResult>> ExtractFacets(IFacetExtractionContext facetExtractionContext)
         {
             Facets facetCounts = facetExtractionContext.GetFacetCounts(FacetField, false);