You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@metron.apache.org by "ASF GitHub Bot (JIRA)" <ji...@apache.org> on 2017/02/20 05:13:44 UTC
[jira] [Commented] (METRON-725) Javadoc is broken by the use of
apiNote
[ https://issues.apache.org/jira/browse/METRON-725?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15874039#comment-15874039 ]
ASF GitHub Bot commented on METRON-725:
---------------------------------------
GitHub user justinleet opened a pull request:
https://github.com/apache/incubator-metron/pull/458
METRON-725: Javadoc is broken by the use of apiNote
As noted in the ticket, there are 3 options for fixing this
1. Just delete the offending inherited javadoc
2. Explicitly inherit the Javadoc
3. Enable the `@apiNote` tag
This PR just does the first one, but it's easy to change if anybody has a strong preference. I lean pretty heavily towards 1 or 2 (because 3 is apparently more intended towards the Java language, rather than outside usage)
To test, just run mvn javadoc:javadoc.
This also suggests that we should be running this as part of our normal build process (and I'll create a ticket if people agree).
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/justinleet/incubator-metron javadoc_fixes
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/incubator-metron/pull/458.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 #458
----
commit 1e1dbbd71da13570767c7025f0aed8b0b801205a
Author: justinjleet <ju...@gmail.com>
Date: 2017-02-20T05:06:51Z
Removing already inherited Javadoc
----
> Javadoc is broken by the use of apiNote
> ---------------------------------------
>
> Key: METRON-725
> URL: https://issues.apache.org/jira/browse/METRON-725
> Project: Metron
> Issue Type: Bug
> Reporter: Justin Leet
> Assignee: Justin Leet
> Priority: Minor
>
> Error seen:
> {code}
> >mvn javadoc:javadoc
> ...
> [ERROR] /Users/jleet/Documents/workspace/incubator-metron/metron-platform/metron-common/src/main/java/org/apache/metron/common/utils/file/ReaderSpliterator.java:127: error: unknown tag: apiNote
> ...
> {code}
> {{@apiNote}} doesn't work by default when generating Javadocs. Apparently, it's intended to be language level information rather than a widely adopted tag.
> This only shows up in ReaderSpliterator, in docs copied directly from the language construct. Given that all these methods are {{@Override}}, it seems reasonable to just drop the docs entirely, given that they inherit anyway.
> If desired, we could explicitly inherit the parent docs.
> Finally, we could enable the use of {{@apiNote}}, but given the intended usage and our copied use, I'm inclined to just change our code directly.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)