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 <[email protected]>
Date: 2017-01-04T14:02:44Z
Lucene.Net.Core.Util.AttributeSource refactor: renamed private/internal
fields camelCase
commit 36a07f671994692727ead370658f535f3024e617
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:03:50Z
Lucene.Net.Core.Util.CollectionUtil refactor: renamed private/internal
fields camelCase
commit aca3935fd6a110d5f2f5f96026d17877defbd23a
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:04:25Z
Lucene.Net.Core.Util.Counter refactor: renamed private/internal fields
camelCase
commit 98e709aaddbe0726789692731ba7af5fef35c8b6
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:04:58Z
Lucene.Net.Core.Util.DocIdBitSet refactor: renamed private/internal fields
camelCase
commit f7beea039ea9512b3363be21c22859c783db6936
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:06:04Z
Lucene.Net.Core.Util.FixedBitSet refactor: renamed private/internal fields
camelCase
commit a07f85eb9e836fc837a9992289d828a05b1c27e4
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:07:05Z
Lucene.Net.Core.Util.IndexableBinaryStringTools refactor: renamed
private/internal fields camelCase
commit 13285db6a5e9d4dad6bbb44eedf18fa9c7e7581f
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:07:47Z
Lucene.Net.Core.Util.OfflineSorter refactor: renamed private/internal
fields camelCase
commit 770291e992490a6fb3a33ba872e8575e58b49f9c
Author: Shad Storhaug <[email protected]>
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 <[email protected]>
Date: 2017-01-04T14:25:47Z
Lucene.Net.Util.Fst.FST.ArcAndState refactor: changed internal fields to
properties
commit 62428a057e4b231dc7e5708d73c7ebb5a0347ce8
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:27:07Z
Lucene.Net.Util.Fst.Util refactor: renamed private/internal fields camelCase
commit 847e48404b4a9fc1833fb9bdf6a40648ef9280e4
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:29:24Z
Lucene.Net.Util.Automaton.BasicOperations refactor: renamed
private/internal fields camelCase
commit 57422157067bca9f0b9bb851815d9381966869e1
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:30:46Z
Lucene.Net.Store.CompoundFileDirectory refactor: renamed private/internal
fields camelCase
commit 56fa68b51a5e1cd0f92a094f9d581af247aa5e24
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:31:52Z
Lucene.Net.Store.CompoundFileWriter refactor: renamed private/internal
fields camelCase
commit 42404dcb0b7bd363c0220c85358995e0d8855c6d
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:33:02Z
Lucene.Net.Store.FSDirectory refactor: renamed private/internal fields
camelCase
commit 79dca6e5df09b18e290cff9816adc7a204023335
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:33:37Z
Lucene.Net.Store.Lock refactor: renamed private/internal fields camelCase
commit 002c01c0c779677c21647bd2a0fbbf7a16f8c3db
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:35:07Z
Lucene.Net.Search.BooleanQuery refactor: renamed private/internal fields
camelCase
commit 226473f3b9ba91908960d228d5a05d2536b8fbcf
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:36:16Z
Lucene.Net.Search.BooleanScorer refactor: renamed private/internal fields
camelCase
commit 6097448be962a835fa274be0e47c503302dfa2cb
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:37:53Z
Lucene.Net.Search.BooleanScorer2 refactor: renamed private/internal fields
camelCase
commit f208331fe7978fdb060b06f32310aee9ea42425e
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:38:28Z
Lucene.Net.Search.ConjunctionScorer refactor: renamed private/internal
fields camelCase
commit b340368a7e792f6a638c8f138fddda1fa520e40b
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:39:57Z
Lucene.Net.Search.ConstantScoreAutoRewrite refactor: renamed
private/internal fields camelCase
commit cbae07a115d7e616a5b769a977499722f68faaa8
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:40:44Z
Lucene.Net.Search.SortRescorer refactor: renamed private/internal fields
camelCase
commit e3a0c3d3786d4d3e5852312971a91c9ba182781c
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:42:17Z
Lucene.Net.Search.Spans.SpanOrQuery refactor: renamed private/internal
fields camelCase
commit ab3570c5ac010df08b58571dc66fbc49cc6db16e
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:45:36Z
Lucene.Net.Index.ConcurrentMergeScheduler refactor: renamed
private/internal fields camelCase
commit 553959d46c1a1ba1c5c3987e4975baa1549329e9
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:49:14Z
Lucene.Net.Index.DocTermOrds refactor: renamed private/internal fields
camelCase
commit 0bc588f7d78c5d83d6f86485bf5be16625b9f930
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:51:31Z
Lucene.Net.Index.DocValues refactor: renamed private/internal fields
camelCase
commit 135de260199ccbcff38f525fd7b7ac0423d63bc8
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:52:21Z
Lucene.Net.Index.MultiDocValues refactor: renamed private/internal fields
camelCase
commit d15d9c78aeed4ff64b51dddb4a88bf03ccc22a54
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:53:06Z
Lucene.Net.Index.PrefixCodedTerms refactor: renamed private/internal fields
camelCase
commit 1bfcb5c59ca2143947ca82225ae83122618f3b74
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:55:12Z
Lucene.Net.Documents.Field refactor: renamed private/internal fields
camelCase
commit 0adb11baf81265825e7ab14d9ba784ef902f363b
Author: Shad Storhaug <[email protected]>
Date: 2017-01-04T14:56:07Z
Lucene.Net.Core.Codecs.DocValuesConsumer refactor: renamed private/internal
fields camelCase
commit 9af294db60a33531b444d1faf714267db0855e60
Author: Shad Storhaug <[email protected]>
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 [email protected] or file a JIRA ticket
with INFRA.
---
