lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Shad Storhaug (JIRA)" <j...@apache.org>
Subject [jira] [Updated] (LUCENENET-616) Make Collections from Lucene.Net.Support into a 1st Class Feature
Date Wed, 14 Aug 2019 01:17:00 GMT

     [ https://issues.apache.org/jira/browse/LUCENENET-616?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Shad Storhaug updated LUCENENET-616:
------------------------------------
    Description: 
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
# 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.

  was:
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
# There should be a "namespace document" 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.


> 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
>            Priority: Major
>
> 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
> # 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.



--
This message was sent by Atlassian JIRA
(v7.6.14#76016)

Mime
View raw message