lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From NightOwl888 <...@git.apache.org>
Subject [GitHub] lucenenet pull request #203: API Work - Stabilization
Date Wed, 25 Jan 2017 06:29:30 GMT
GitHub user NightOwl888 opened a pull request:

    https://github.com/apache/lucenenet/pull/203

    API Work - Stabilization

    This is a branch of #191 and supersedes that pull request. To build this branch, see the
instructions on #191.
    
    The plan is to work on the API here to keep from releasing several successive releases
with breaking API changes. Once the API is relatively stable, we can merge to master and create
a release that can be consumed without having to worry about so many breaking API changes
between releases.
    
    > DO NOT MERGE this pull request until the API is stable and failing tests are addressed.
    
    ## API Polishing
    
    This fixes several API issues that were making Lucene.Net deviate from looking like a
normal .NET application - mainly by using properties and methods the way that are specified
in the [MSDN guidelines](https://msdn.microsoft.com/en-us/library/ms229054(v=vs.100).aspx)
and following .NET naming conventions for properties, methods, fields, parameters, and types.
Also several types are being renamed and/or moved to address naming collisions, incorrect
porting corrected, bugs fixed, and other issues such as CLS compliance are being addressed.
    
    These specific changes are being made that make Lucene.Net differ from Lucene because
they are framework conventions that are different between Java and .NET:
    
    1. Interfaces start with "I"
    2. `Size()` changed to `Count` or `Length` property
    3. `Comparator` changed to `Comparer` on all classes, interfaces , properties, methods,
documentation and comments
    4. Type names in methods and properties being .NETified. For example instead of `.SetLongValue(long)`,
we will have `.SetInt64Value()`. NOTE: This isn't done yet. I could use some advice on if
or how this one should be done, since `SetVInt64()` admittedly looks odd. Clearly, we can't
change the class and interface names to match because there are types in the same context
where `Single` means "singular" rather than the `float` data type, and it would be confusing,
but in .NET the names don't match anyway (`Convert.ToInt64()` returns type `long`) so I think
that would be okay.
    
    ## Status
    
    #### Key:
    
    1. Type and Member Accessibility
    2. Properties vs Methods
    3. Properties vs Fields
    4. Method, Property, Field, and Parameter Naming Conventions
    5. Class and Interface Naming Conventions
    6. No Nullable Enums
    7. Parameter and Return Types (IDictionary and IList rather than Dictionary and List)
    8. CLS Compliant
    9. Compiler Warnings Remaining (corresponding test project included)
    10. TODOs Remaining (search for `LUCENENET TODO:` or `LUCENE TO-DO` to find them)
    -------
    
    | Project | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
    |  :---      | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
:---: | 
    | Core                       | X |  | X |  | X |  | ? |  | 109 | 267 |
    | Analysis.Common  |  |  |  |  |  | X | ? | X | 22 | 23 |
    | Analysis.Stempel    | X | ? | ? | ? | ? | ? | ? | X | 0 | 0 |
    | Classification          |  | ? | ? | ? | ? | ? | ? | X | 0 | 0 |
    | Codecs                   | ? | ? | ? | ? | ? | ? | ? | X | 0 | 5 |
    | Expressions            |  | ? | ? | ? | ? | ? | ? | X | 0 | 0 |
    | Facet                      |  X | ? | ? | ? | ? | ? | ? | X | 6 | 14 |
    | Grouping               |  X | ? | ? | ? | ? | ? | ? | X | 0 | 8 |
    | Highlighter            |  X | ? | ? | ? | ? | ? | ? | X | 0 | 6 |
    | Join                        |  | ? | ? | ? | ? | ? | ? | X | 0 | 1 |
    | Memory                 |  X | ? | ? | ? | ? | ? | ? | X | 0 | 0 |
    | Misc                       |  X | ? | ? | ? | ? | ? | ? | X | 8 | 6 |
    | Queries                  |   | ? | ? | ? | ? | ? | ? | X | 0 | 3 |
    | QueryParser           |  X | ? | ? | ? | ? | ? | ? | X | 2 | 20 |
    | Sandbox                 |  X | ? | ? | ? | ? | ? | ? | X | 0 | 0 |
    | Spatial                    |  X | ? | ? | ? | ? | ? | ? | X | 0 | 3 |
    | Suggest                  | X | ? | ? | ? | ? | ? | ? | X | 0 | 4 |
    | Test Framework      | N/A | N/A | N/A |  N/A | N/A | N/A | N/A | N/A | 4 | 5 |
    
    ### Tests
    
    Do note that currently this branch has more failing tests than master. In fact, the test
suite is currently crashing for several tests, making the whole thing bomb before it can finish.
Right now, the priority is finishing the API changes before addressing these problems. 
    
    However, if you would like to help out by debugging the failing tests, please fork [this
branch](https://github.com/apache/lucenenet/tree/api-work) and submit the pull request back
here. Due to the fast changing state of the API, please fix one bug at a time and submit the
pull request to [this branch](https://github.com/apache/lucenenet/tree/api-work) (not master)
ASAP.
    
    ### Documentation Comments
    
    Also up-for-grabs is to complete the documentation comments in the following projects.
    
    1. Core
    2. Analysis.Common
    3. Classification
    4. Expressions
    5. Grouping
    6. Join
    7. Queries
    
    While it is assumed that the documentation comments for the other projects are finished,
they could probably all use a review.
    
    The automated Java converter brought much of the comment structure over, however some
comments have been left behind in Lucene, and they need to be formatted and corrected to match
[MSDN's guidelines](https://msdn.microsoft.com/en-us/library/5ast78ax.aspx). Some common issues
that need to be addressed:
    
    1. Change `seealso` to `see` (`seealso` are for the links that go at the bottom of the
documentation page, not the direct links within the content).
    2. `{@code paramName}` or `<code>paramName</code> need to be changed to `<paramref
name="paramName">`. Note that not all of the "code" are parameter names, and the normal
case need to be in `<c></c>` tags for single line and `<code></code>`
tags for multiline code examples. Do note the code also needs to be converted to match our
API.
    3. `{@link TypeName}` need to be changed to the appropriate `<see cref="TypeName"/>`
or anchor tag (if external).
    4. Many times in the documentation, the types are referred to (in Pascal case) with no
link. In these cases a link to the type should be added (change `TypeName` to `<see cref="TypeName"/>`).
    
    > Be sure to check the comments against [Lucene 4.8.0](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene)
to ensure they are correct and complete!
    
    Pull requests should be directed to [this branch](https://github.com/apache/lucenenet/tree/api-work)
(not master).


You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/apache/lucenenet api-work

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/lucenenet/pull/203.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #203
    
----
commit 956ecf044c0e5c22cf63f46a351e379adb0e7c7b
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:02:44Z

    Lucene.Net.Core.Util.AttributeSource refactor: renamed private/internal fields camelCase

commit 36a07f671994692727ead370658f535f3024e617
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:03:50Z

    Lucene.Net.Core.Util.CollectionUtil refactor: renamed private/internal fields camelCase

commit aca3935fd6a110d5f2f5f96026d17877defbd23a
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:04:25Z

    Lucene.Net.Core.Util.Counter refactor: renamed private/internal fields camelCase

commit 98e709aaddbe0726789692731ba7af5fef35c8b6
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:04:58Z

    Lucene.Net.Core.Util.DocIdBitSet refactor: renamed private/internal fields camelCase

commit f7beea039ea9512b3363be21c22859c783db6936
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:06:04Z

    Lucene.Net.Core.Util.FixedBitSet refactor: renamed private/internal fields camelCase

commit a07f85eb9e836fc837a9992289d828a05b1c27e4
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:07:05Z

    Lucene.Net.Core.Util.IndexableBinaryStringTools refactor: renamed private/internal fields
camelCase

commit 13285db6a5e9d4dad6bbb44eedf18fa9c7e7581f
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:07:47Z

    Lucene.Net.Core.Util.OfflineSorter refactor: renamed private/internal fields camelCase

commit 770291e992490a6fb3a33ba872e8575e58b49f9c
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:23:44Z

    LuceneTestCase: Modified field scan to test field name for < to identify auto-implemented
properties.

commit a8a716a738da3404edf7273a954a67098a69bb1e
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:25:47Z

    Lucene.Net.Util.Fst.FST.ArcAndState refactor: changed internal fields to properties

commit 62428a057e4b231dc7e5708d73c7ebb5a0347ce8
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:27:07Z

    Lucene.Net.Util.Fst.Util refactor: renamed private/internal fields camelCase

commit 847e48404b4a9fc1833fb9bdf6a40648ef9280e4
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:29:24Z

    Lucene.Net.Util.Automaton.BasicOperations refactor: renamed private/internal fields camelCase

commit 57422157067bca9f0b9bb851815d9381966869e1
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:30:46Z

    Lucene.Net.Store.CompoundFileDirectory refactor: renamed private/internal fields camelCase

commit 56fa68b51a5e1cd0f92a094f9d581af247aa5e24
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:31:52Z

    Lucene.Net.Store.CompoundFileWriter refactor: renamed private/internal fields camelCase

commit 42404dcb0b7bd363c0220c85358995e0d8855c6d
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:33:02Z

    Lucene.Net.Store.FSDirectory refactor: renamed private/internal fields camelCase

commit 79dca6e5df09b18e290cff9816adc7a204023335
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:33:37Z

    Lucene.Net.Store.Lock refactor: renamed private/internal fields camelCase

commit 002c01c0c779677c21647bd2a0fbbf7a16f8c3db
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:35:07Z

    Lucene.Net.Search.BooleanQuery refactor: renamed private/internal fields camelCase

commit 226473f3b9ba91908960d228d5a05d2536b8fbcf
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:36:16Z

    Lucene.Net.Search.BooleanScorer refactor: renamed private/internal fields camelCase

commit 6097448be962a835fa274be0e47c503302dfa2cb
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:37:53Z

    Lucene.Net.Search.BooleanScorer2 refactor: renamed private/internal fields camelCase

commit f208331fe7978fdb060b06f32310aee9ea42425e
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:38:28Z

    Lucene.Net.Search.ConjunctionScorer refactor: renamed private/internal fields camelCase

commit b340368a7e792f6a638c8f138fddda1fa520e40b
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:39:57Z

    Lucene.Net.Search.ConstantScoreAutoRewrite refactor: renamed private/internal fields camelCase

commit cbae07a115d7e616a5b769a977499722f68faaa8
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:40:44Z

    Lucene.Net.Search.SortRescorer refactor: renamed private/internal fields camelCase

commit e3a0c3d3786d4d3e5852312971a91c9ba182781c
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:42:17Z

    Lucene.Net.Search.Spans.SpanOrQuery refactor: renamed private/internal fields camelCase

commit ab3570c5ac010df08b58571dc66fbc49cc6db16e
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:45:36Z

    Lucene.Net.Index.ConcurrentMergeScheduler refactor: renamed private/internal fields camelCase

commit 553959d46c1a1ba1c5c3987e4975baa1549329e9
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:49:14Z

    Lucene.Net.Index.DocTermOrds refactor: renamed private/internal fields camelCase

commit 0bc588f7d78c5d83d6f86485bf5be16625b9f930
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:51:31Z

    Lucene.Net.Index.DocValues refactor: renamed private/internal fields camelCase

commit 135de260199ccbcff38f525fd7b7ac0423d63bc8
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:52:21Z

    Lucene.Net.Index.MultiDocValues refactor: renamed private/internal fields camelCase

commit d15d9c78aeed4ff64b51dddb4a88bf03ccc22a54
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:53:06Z

    Lucene.Net.Index.PrefixCodedTerms refactor: renamed private/internal fields camelCase

commit 1bfcb5c59ca2143947ca82225ae83122618f3b74
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:55:12Z

    Lucene.Net.Documents.Field refactor: renamed private/internal fields camelCase

commit 0adb11baf81265825e7ab14d9ba784ef902f363b
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:56:07Z

    Lucene.Net.Core.Codecs.DocValuesConsumer refactor: renamed private/internal fields camelCase

commit 9af294db60a33531b444d1faf714267db0855e60
Author: Shad Storhaug <shad@shadstorhaug.com>
Date:   2017-01-04T14:58:25Z

    Lucene.Net.Core.Codecs.PerField.PerFieldDocValuesFormat refactor: renamed private/internal
fields camelCase

----


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message