Bipin Prasad created STORM-3931:
-----------------------------------
Summary: @see tags that are followed by {@link...}
Key: STORM-3931
URL: https://issues.apache.org/jira/browse/STORM-3931
Project: Apache Storm
Issue Type: Task
Components: documentation
Reporter: Bipin Prasad
@see tags have been deprected in JDK9 in favor of @link tags.
In Storm, several source files contain improperly formatted '@see' tags. This
tag expects class name otherwise generates error for unexpected "{" - character
code 123 and "@", character code 64. When generating javadoc.
{code:java}
[INFO] [WARNING]
.../storm/storm-client/src/jvm/org/apache/storm/utils/DefaultShellLogHandler.java:51:
warning - Tag @see:illegal character: "123" in "{@link
ShellLogHandler#setUpContext}"
[INFO] [WARNING]
.../storm/storm-client/src/jvm/org/apache/storm/utils/DefaultShellLogHandler.java:51:
warning - Tag @see:illegal character: "64" in "{@link
ShellLogHandler#setUpContext}"
[INFO] [WARNING]
.../storm/storm-client/src/jvm/org/apache/storm/utils/DefaultShellLogHandler.java:51:
warning - Tag @see: reference not found: "{@link ShellLogHandler#setUpContext}"
{code}
For example
storm-client/src/jvm/org/apache/storm/utils/DefaultShellLogHandler.java#setUpContext
{code:java}
/**
* This default implementation saves the {@link ShellProcess} so it can output
the process info string later.
*
* @param ownerCls - the class which instantiated this ShellLogHandler.
* @param process - the current {@link ShellProcess}.
* @param context - the current {@link TopologyContext}.
* @see {@link ShellLogHandler#setUpContext}
*/
{code}
Should just be rolled into the documentation thusly:
{code:java}
/**
* This default implementation saves the {@link ShellProcess} so it can output
the process info string later. See {@link ShellLogHandler#setUpContext}.
*
* @param ownerCls - the class which instantiated this ShellLogHandler.
* @param process - the current {@link ShellProcess}.
* @param context - the current {@link TopologyContext}.
*/
{code}
or
{code:java}
/**
* This default implementation saves the {@link ShellProcess} so it can output
the process info string later.
*
* @param ownerCls - the class which instantiated this ShellLogHandler.
* @param process - the current {@link ShellProcess}.
* @param context - the current {@link TopologyContext}.
* @see ShellLogHandler#setUpContext
*/
{code}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
