retrospectively add @since javadocs for 'intervals' classes [LUCENE-8733]

[asfimport]

#9243 started 'intervals' and subsequent tickets extended it.

This ticket proposes to retrospectively add ``@since X.Y javadocs for all the classes (and to then going forward perhaps continue to add them).

And perhaps we could have an 'intervals' or similar JIRA components choice too?

---

Migrated from LUCENE-8733 by Christine Poerschke (@cpoerschke), updated Mar 22 2019
Attachments: LUCENE-8733-branch-7-4.patch

[asfimport]

Christine Poerschke (@cpoerschke) (migrated from JIRA)

Attached LUCENE-8733-branch-7-4.patch and would propose to commit that to branch_7_4 and then from there cherry-pick it 'upwards' to branch_7_5, branch_7_6, branch_7_7, branch_8_0 and master branches. And then to repeat the process i.e. LUCENE-8733-branch-7-5.patch (not yet created) would go to branch_7_5 first and then upwards. How does that sound?

[asfimport]

Adrien Grand (@jpountz) (migrated from JIRA)

Most of the classes whose documentation is updated are package-private, so this will never show up in javadocs?

[asfimport]

Christine Poerschke (@cpoerschke) (migrated from JIRA)

Most of the classes whose documentation is updated are package-private ...

Understood. It seems easier though to just add it for all the classes in the package rather than consider on each one if it's required or not?

... so this will never show up in javadocs?

Yes and no. It will not show up in the https://lucene.apache.org/core published javadocs, yes. However it would still be visible in developers' IDE (perhaps there's a different way to obtain visibility there too, haven't looked into) and also it's possible to re-generate more extended javadocs locally e.g. via

ant javadocs -Djavadoc.access=private

(something I learnt 'way back when' on #7629 ticket).

[asfimport]

Adrien Grand (@jpountz) (migrated from JIRA)

I have mixed feelings. I have never found the "@since" tag very helpful, though I can understand how some users could find it useful on important APIs, eg. maybe things like BooleanQuery, FeatureField, LongPoint. However here we are updating javadocs of package-private classes in the sandbox, so it's unclear to me to whom it is going to be helpful? I'm not opposed to adding those, but a bit surprised. I'd be curious to better understand your motivation?

[asfimport]

Christine Poerschke (@cpoerschke) (migrated from JIRA)

... curious to better understand your motivation?

The use case I guess is to be able to 'browse' (probably more likely in IDE than via re-generated javadocs) on a 'current' branch of the repo i.e. currently branch_8x (or possibly master) and to easily see for the brand-new stuff in sandbox if it was already available in the version of the software that one is currently running and if not from what version onwards it is available. Of course the info would also be available in other ways e.g. CHANGES.txt and JIRA tickets but 'with the code' seems quite helpful specifically in the sandbox scenario. And I'm not suggesting we move towards having "@since" tags all over the place or in an automatically enforced way, it's just here specifically with intervals in the sandbox I would find the presence of such tags helpful :)

[asfimport]

Alan Woodward (@romseygeek) (migrated from JIRA)

I think it's reasonable to have them on the public API, which in this case is the Intervals class and its static factory methods, and IntervalQuery itself. I don't really like having them on internal classes though, as they're an implementation detail, and users of intervals shouldn't need to know about them at all.

[asfimport]

Jason Gerlowski (@gerlowskija) (migrated from JIRA)

I don't really like having them on internal classes though, they're an implementation detail, and users of intervals shouldn't need to know about them at all.

True, but if the package-private Javadocs aren't published, is this really a concern? If these internal Javadocs are only exposed to those browsing in an IDE, users are only going to stumble across them if they've already decided they want (or need) to look at Lucene's internals. They're going to see the internals with or without the @since.

Am I missing something here? I don't see anything wrong with adding the tags if it makes lives easier for some developers, but maybe I just don't understand the argument against...