Merge pull request #312 from nikcio/chore/facets-xml

Facets XML (#311)

src/Examine.Core/BaseIndexProvider.cs

@@ -6,7 +6,6 @@
 
 namespace Examine
 {
-    /// <inheritdoc />
     /// <summary>
     /// Base class for an Examine Index Provider
     /// </summary>
@@ -18,9 +17,9 @@ public abstract class BaseIndexProvider : IIndex
         /// <summary>
         /// Constructor for creating an indexer at runtime
         /// </summary>
+        /// <param name="loggerFactory"></param>
         /// <param name="name"></param>
-        /// <param name="fieldDefinitions"></param>
-        /// <param name="validator"></param>
+        /// <param name="indexOptions"></param>
         protected BaseIndexProvider(ILoggerFactory loggerFactory, string name,
             IOptionsMonitor<IndexOptions> indexOptions)
         {
@@ -33,7 +32,12 @@ protected BaseIndexProvider(ILoggerFactory loggerFactory, string name,
             _indexOptions = indexOptions.GetNamedOptions(name);
         }
 
+        /// <summary>
+        /// The factory used to create instances of <see cref="ILogger"/>.
+        /// </summary>
         protected ILoggerFactory LoggerFactory { get; }
+
+        /// <inheritdoc/>
         public virtual string Name { get; }
 
         /// <summary>
@@ -73,11 +77,11 @@ protected abstract void PerformDeleteFromIndex(IEnumerable<string> itemIds,
 
         #region IIndex members
 
+        /// <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)
@@ -91,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
@@ -125,20 +122,24 @@ public void DeleteFromIndex(IEnumerable<string> itemIds)
 
         #region Protected Event callers
 
+        /// <summary>
+        /// Run when a index operation completes
+        /// </summary>
+        /// <param name="e"></param>
         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) =>

src/Examine.Core/BaseSearchProvider.cs

@@ -8,20 +8,17 @@ namespace Examine
     ///</summary>
     public abstract class BaseSearchProvider : ISearcher
     {
+        /// <inheritdoc/>
         protected BaseSearchProvider(string name)
         {
             if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("Value cannot be null or whitespace.", nameof(name));
             Name = name;
         }
 
+        /// <inheritdoc/>
         public string Name { get; }
 
-        /// <summary>
-        /// Searches the index
-        /// </summary>
-        /// <param name="searchText"></param>
-        /// <param name="maxResults"></param>
-        /// <returns></returns>
+        /// <inheritdoc/>
         public abstract ISearchResults Search(string searchText, QueryOptions options = null);
 
         /// <inheritdoc />

src/Examine.Core/DisposableObjectSlim.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 
 namespace Examine
 {   
@@ -10,11 +10,13 @@ public abstract class DisposableObjectSlim : IDisposable
     {
         private readonly object _locko = new object();
 
-        // gets a value indicating whether this instance is disposed.
-        // for internal tests only (not thread safe)
+        /// <summary>
+        /// Gets a value indicating whether this instance is disposed.
+        /// for internal tests only (not thread safe)
+        /// </summary>
         protected bool Disposed { get; private set; }
 
-        // implements IDisposable
+        /// <inheritdoc/>
         public void Dispose()
         {
             Dispose(true);
@@ -32,6 +34,9 @@ private void Dispose(bool disposing)
                 DisposeResources();
         }
 
+        /// <summary>
+        /// Used to dispose resources
+        /// </summary>
         protected abstract void DisposeResources();
     }
-}
+}

src/Examine.Core/EmptySearchResults.cs

@@ -4,34 +4,45 @@
 
 namespace Examine
 {
+    /// <summary>
+    /// Represents <see cref="ISearchResults"/> with no elements
+    /// </summary>
 	public sealed class EmptySearchResults : ISearchResults
 	{
         private EmptySearchResults()
         {   
         }
 
+        /// <summary>
+        /// Gets the static instance
+        /// </summary>
 	    public static ISearchResults Instance { get; } = new EmptySearchResults();
 
+        /// <inheritdoc/>
         public IEnumerator<ISearchResult> GetEnumerator()
 		{
 			return Enumerable.Empty<ISearchResult>().GetEnumerator();
 		}
 
-		IEnumerator IEnumerable.GetEnumerator()
+        /// <inheritdoc/>
+        IEnumerator IEnumerable.GetEnumerator()
 		{
 			return Enumerable.Empty<ISearchResult>().GetEnumerator();
 		}
 
+        /// <inheritdoc/>
 		public long TotalItemCount => 0;
 
-	    public IEnumerable<ISearchResult> Skip(int skip)
+        /// <inheritdoc/>
+        public IEnumerable<ISearchResult> Skip(int skip)
 		{
 			return Enumerable.Empty<ISearchResult>();
 		}
 
+        /// <inheritdoc/>
         public IEnumerable<ISearchResult> SkipTake(int skip, int? take = null)
         {
 			return Enumerable.Empty<ISearchResult>();
 		}
     }
-}
+}

src/Examine.Core/Examine.Core.csproj

@@ -5,6 +5,7 @@
     <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
     <Description>Examine is an abstraction for indexing and search operations with implementations such as Lucene.Net</Description>
     <PackageTags>examine search index</PackageTags>
+    <GenerateDocumentationFile>True</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>

src/Examine.Core/ExamineExtensions.cs

@@ -8,6 +8,14 @@ namespace Examine
     /// </summary>
     public static class ExamineExtensions
     {
+        /// <summary>
+        /// Gets named options from an <see cref="IOptionsMonitor{TOptions}"/>
+        /// </summary>
+        /// <typeparam name="T"></typeparam>
+        /// <param name="optionsMonitor"></param>
+        /// <param name="name"></param>
+        /// <returns></returns>
+        /// <exception cref="InvalidOperationException"></exception>
         public static T GetNamedOptions<T>(this IOptionsMonitor<T> optionsMonitor, string name)
             where T : class
         {
@@ -36,6 +44,11 @@ public static IIndex GetIndex(this IExamineManager examineManager, string indexN
             throw new InvalidOperationException("No index found with name " + indexName);
         }
 
+        /// <summary>
+        /// Deletes a node from the index
+        /// </summary>
+        /// <param name="index"></param>
+        /// <param name="itemId"></param>
         public static void DeleteFromIndex(this IIndex index, string itemId)
         {
             index.DeleteFromIndex(new[] {itemId});

src/Examine.Core/ExamineFieldNames.cs

@@ -1,5 +1,8 @@
 namespace Examine
 {
+    /// <summary>
+    /// Constant names for speciffic fields
+    /// </summary>
     public static class ExamineFieldNames
     {
         /// <summary>
@@ -22,6 +25,9 @@ public static class ExamineFieldNames
         /// </summary>
         public const string ItemIdFieldName = "__NodeId";
 
+        /// <summary>
+        /// Used to store the item type for a document
+        /// </summary>
         public const string ItemTypeFieldName = "__NodeTypeAlias";
 
         /// <summary>

src/Examine.Core/ExamineManager.cs

@@ -10,6 +10,7 @@ namespace Examine
     ///</summary>
     public class ExamineManager : IDisposable, IExamineManager
     {
+        /// <inheritdoc/>
         public ExamineManager(IEnumerable<IIndex> indexes, IEnumerable<ISearcher> searchers)
         {
             foreach(IIndex i in indexes)
@@ -68,6 +69,8 @@ private ISearcher AddSearcher(ISearcher searcher)
         public void Dispose() => Dispose(true);
 
         private bool _disposed = false;
+
+        /// <inheritdoc/>
         protected virtual void Dispose(bool disposing)
         {
             if (!_disposed)

src/Examine.Core/FieldDefinition.cs

@@ -30,14 +30,17 @@ public FieldDefinition(string name, string type)
         /// </summary>
         public string Type { get; }
 
+        /// <inheritdoc/>
         public bool Equals(FieldDefinition other) => string.Equals(Name, other.Name) && string.Equals(Type, other.Type);
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             if (ReferenceEquals(null, obj)) return false;
             return obj is FieldDefinition definition && Equals(definition);
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             unchecked
@@ -46,8 +49,10 @@ public override int GetHashCode()
             }
         }
 
+        /// <inheritdoc/>
         public static bool operator ==(FieldDefinition left, FieldDefinition right) => left.Equals(right);
 
+        /// <inheritdoc/>
         public static bool operator !=(FieldDefinition left, FieldDefinition right) => !left.Equals(right);
     }
 }

src/Examine.Core/FieldDefinitionCollection.cs

@@ -2,16 +2,29 @@
 
 namespace Examine
 {
+    /// <inheritdoc/>
     public class FieldDefinitionCollection : ReadOnlyFieldDefinitionCollection
     {
+        /// <inheritdoc/>
         public FieldDefinitionCollection(params FieldDefinition[] definitions) : base(definitions)
         {
         }
 
+        /// <inheritdoc/>
         public FieldDefinitionCollection()
         {
         }
 
+        /// <summary>
+        /// 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>
+        /// <param name="fieldName"></param>
+        /// <param name="add"></param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">fieldName or add is null</exception>
+        /// <exception cref="OverflowException">The dictionary already contains the maximum number of elements (<see cref="int.MaxValue"/>)</exception>
         public FieldDefinition GetOrAdd(string fieldName, Func<string, FieldDefinition> add) => Definitions.GetOrAdd(fieldName, add);
 
         /// <summary>
@@ -20,6 +33,16 @@ public FieldDefinitionCollection()
         /// <param name="definition"></param>
         public void AddOrUpdate(FieldDefinition definition) => Definitions.AddOrUpdate(definition.Name, definition, (s, factory) => definition);
 
+        /// <summary>
+        /// 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 <see cref="System.Collections.Concurrent.ConcurrentDictionary{TKey, TValue}"/>
+        /// successfully; false if the key already exists.
+        /// </returns>
+        /// <exception cref="ArgumentNullException">definition.Name is null</exception>
+        /// <exception cref="OverflowException">The dictionary already contains the maximum number of elements (<see cref="int.MaxValue"/>)</exception>
         public bool TryAdd(FieldDefinition definition) => Definitions.TryAdd(definition.Name, definition);
     }
 }