Affects Version/s: Lucene.Net 4.8.0
Fix Version/s: None
Component/s: Lucene.Net Core
The collection types in Lucene.Net.Support were originally sourced to support Lucene.Net itself. While they were made public, they were not considered to be features that would be used by anyone except for advanced users.
However, it has become clear by user reports that some parts of Lucene's design require specialized collections that don't exist in the .NET Framework in order to properly function (see LUCENENET-612 and LUCENENET-615. .NET users are generally not familiar with these specialized collection types and assume that when IDictionary<TKey, TValue> is required by an API that using Dictionary<TKey, TValue> is their best choice. We need to improve documentation and increase visibility of the specialized collection types in order to help them along.
- The collection types should be moved to a new Lucene.Net.Collections.Specialized namespace
- The collection types should stay in the Support folder, but be moved into a Collections/Specialized subfolder. The Collections class needs to be renamed to prevent a naming conflict - I suggest following the same approach that was done in ICU4N's Support folder, by making many of them into extension methods.
- The collection types should be named consistently according to .NET conventions, for example HashMap should be renamed HashDictionary
- We should ensure we have a full set of tests for each collection, and that each collection is fully implemented
- All collections must implement the expected interfaces from System.Collections, for example a generic dictionary should implement System.Collections.Generic.IDictionary<TKey, TValue>
- The documentation for each collection should not just indicate where it was grabbed from, but explain fully how it behaves and how its behavior differs from other collection types
- APIs where it is known that specialized collections were intended to be used should also be documented to indicate the choices the end user has so they don't automatically assume they are constrained by the .NET framework's collection types
- There should be a "namespace document" in Lucene.Net.Collections.Generic that lists all of the collection types and a summary of their behavior, so they can be comparison shopped easily
Since these are breaking API changes, they should be done before the official release of Lucene.Net 4.8.0.
Generally speaking, collections were fully implemented and tested to prevent odd bugs from creeping into Lucene.Net but it wouldn't hurt to review to ensure that is the case.