[jira] [Comment Edited] (LUCENE-7129) Prevent @lucene.internal annotated classes from being in Javadocs
[
https://issues.apache.org/jira/browse/LUCENE-7129?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15206543#comment-15206543
]
Uwe Schindler edited comment on LUCENE-7129 at 3/22/16 3:31 PM:
Nevertheless, the whole "filtering" javadocs approach is not useful to prevent
people from using the APIs. Nothing can forbid people or their stupid Eclipse
autocompleter to use the classes we marked as experimental.
The correct fix for this is coming with Java 9, but we can start implementing
it before:
- Move all internal APIs to a separate package (this is what Robert wants to do
anyways), e.g., {{org.apache.lucene.internal}}.
- Don't export this package in {{module-info.java}}, so it gets completely
invisible to anybody using the JAR file as a module ({{-modulepath}} instead of
{{-classpath}}). Only lucene's own modules are allowed to refer to those
packages through explicit export "to".
- Javadoc would work automatically, because Java 9 Javadocs does not document
non-exported packages.
This approach should be done at some point anyways, but it needs some
refactoring of package names. Most is fine, but some JAR files share packages
with others. This is no longer possible with Java 9 modules! E.g., Misc modules
{{oal.index}} package would need to be renamed, because it conflicts with the
module exported by lucene-core.jar.
was (Author: thetaphi):
Nevertheless, the whole "filtering" javadocs approach is not useful to prevent
people from using the APIs. Nothing can forbid people or their stupid Eclipse
autocompleter to use the classes we marked as experimental.
The correct fix for this is coming with Java 9, but we can start implementing
it before:
- Move all internal APIs to a separate package (this is what Robert wants to do
anyways), e.g., {{org.apache.lucene.internal}}.
- Don't export this package in {{module-info.java}}, so it gets completely
invisible to anybody using the JAR file as a module ({{-modulepath}} instead of
{{-classpath}}). Only lucene's own modules are allowed to refer to those
modules.
- Javadoc would work automatically, because Java 9 Javadocs does not document
non-exported packages.
This approach should be done at some point anyways, but it needs some
refactoring of package names. Most is fine, but some JAR files share packages
with others. This is no longer possible with Java 9 modules! E.g., Misc modules
{{oal.index}} package would need to be renamed, because it conflicts with the
module exported by lucene-core.jar.
> Prevent @lucene.internal annotated classes from being in Javadocs
> -
>
> Key: LUCENE-7129
> URL: https://issues.apache.org/jira/browse/LUCENE-7129
> Project: Lucene - Core
> Issue Type: Task
> Components: general/javadocs
>Reporter: David Smiley
>Priority: Minor
>
> It would be cool if we could prevent {{@lucene.internal}} classes from
> appearing in Javadocs we publish. This would further discourage use of
> internal Lucene/Solr classes that are public not for public consumption but
> only public so that the code can be accessed across Lucene/Solr's packages.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Comment Edited] (LUCENE-7129) Prevent @lucene.internal annotated classes from being in Javadocs
[
https://issues.apache.org/jira/browse/LUCENE-7129?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15206514#comment-15206514
]
Uwe Schindler edited comment on LUCENE-7129 at 3/22/16 3:11 PM:
There are two ways to do this:
- Quick'n'dirty: We have to change our filesets (for sources parameter) before
invoking the javadocs macro. As Javadocs processes all java files one by one,
we may use a fileset instead of the generic packageset element inside the
javadoc, excluding those java files we don't want to have. The fileset with tha
java files we pass to javadoc would just need to filter on the contents (file
contains "@lucene.internal" as an additional
[selector|https://ant.apache.org/manual/Types/selectors.html] in the fileset
defintion). Of course this slows down a bit, because Ant has to read all files
while building the fileset.
- More sophisticated: Use our own Doclet that delegates everything to standard
doclet, but handles the tags we want to eclude. Somebody coded this; we could
add to our tools folder: http://sixlegs.com/blog/java/exclude-javadoc-tag.html
(maybe its somewehere in Maven). The issue with doclets is the API hell with
interfaces, but this guy has a good way around that (he dynamically creates a
proxy for every interface and uses it to delegate).
was (Author: thetaphi):
There are two ways to do this:
- Quick'n'dirty: We have to change our filesets (for sources parameter) before
invoking the javadocs macro. As Javadocs processes all java files one by one,
we may use a fileset instead of the generic packageset element iside the
javadoc, excluding those class files we don't want to have. The fileset with
tha java files we pass to javadoc would just need to filter on the contents
(file contains "@lucene.internal" as an additional
[selector|https://ant.apache.org/manual/Types/selectors.html] in the fileset
defintion). Of course this slows down a bit, because Ant has to read all files
while building the fileset.
- More sophisticated: Use our own Doclet that delegates everything to standard
doclet, but handles the tags we want to eclude. Somebody coded this; we could
add to our tools folder: http://sixlegs.com/blog/java/exclude-javadoc-tag.html
(maybe its somewehere in Maven). The issue with doclets is the API hell with
interfaces, but this guy has a good way around that (he dynamically creates a
proxy for every interface and uses it to delegate).
> Prevent @lucene.internal annotated classes from being in Javadocs
> -
>
> Key: LUCENE-7129
> URL: https://issues.apache.org/jira/browse/LUCENE-7129
> Project: Lucene - Core
> Issue Type: Task
> Components: general/javadocs
>Reporter: David Smiley
>Priority: Minor
>
> It would be cool if we could prevent {{@lucene.internal}} classes from
> appearing in Javadocs we publish. This would further discourage use of
> internal Lucene/Solr classes that are public not for public consumption but
> only public so that the code can be accessed across Lucene/Solr's packages.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
