Shad Storhaug created LUCENENET-616:
---------------------------------------
Summary: Make Collections from Lucene.Net.Support into a 1st Class
Feature
Key: LUCENENET-616
URL: https://issues.apache.org/jira/browse/LUCENENET-616
Project: Lucene.Net
Issue Type: Improvement
Components: Lucene.Net Core
Affects Versions: Lucene.Net 4.8.0
Reporter: Shad Storhaug
The collections 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|https://issues.apache.org/jira/projects/LUCENENET/issues/LUCENENET-612]
and
[LUCENENET-615|https://issues.apache.org/jira/projects/LUCENENET/issues/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 only 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.Generic}} namespace
# The collection types should stay in the {{Support}} folder, but be moved into
a {{Support/Collections/Generic}} 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|https://github.com/NightOwl888/ICU4N/tree/master/src/ICU4N/Support].
# 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.Generic}}, for example a 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 differs in behavior 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
Since these are breaking API changes, they should be done before the official
release of Lucene.Net 4.8.0
--
This message was sent by Atlassian JIRA
(v7.6.14#76016)
