[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16799218#comment-16799218
]
Jason Gerlowski commented on LUCENE-8733:
-
bq. 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...
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16798833#comment-16798833
]
Alan Woodward commented on LUCENE-8733:
---
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.
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16798329#comment-16798329
]
Christine Poerschke commented on LUCENE-8733:
-
{quote}... curious to better understand your motivation?
{quote}
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 :)
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16798313#comment-16798313
]
Adrien Grand commented on LUCENE-8733:
--
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?
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16798299#comment-16798299
]
Christine Poerschke commented on LUCENE-8733:
-
bq. 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?
bq. ... 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
{code}
ant javadocs -Djavadoc.access=private
{code}
(something I learnt 'way back when' on LUCENE-6571 ticket).
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16798295#comment-16798295
]
Adrien Grand commented on LUCENE-8733:
--
Most of the classes whose documentation is updated are package-private, so this
will never show up in javadocs?
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (LUCENE-8733) retrospectively add @since javadocs for 'intervals' classes
[
https://issues.apache.org/jira/browse/LUCENE-8733?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16798290#comment-16798290
]
Christine Poerschke commented on LUCENE-8733:
-
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?
> retrospectively add @since javadocs for 'intervals' classes
> ---
>
> Key: LUCENE-8733
> URL: https://issues.apache.org/jira/browse/LUCENE-8733
> Project: Lucene - Core
> Issue Type: Wish
>Reporter: Christine Poerschke
>Assignee: Christine Poerschke
>Priority: Minor
> Attachments: LUCENE-8733-branch-7-4.patch
>
>
> LUCENE-8196 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?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
