JDK-4764045 : javadoc inline tag {@value} should be available everywhere
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0,1.4.1
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: other,linux,windows_2000
  • CPU: generic,x86
  • Submitted: 2002-10-16
  • Updated: 2014-05-05
  • Resolved: 2003-09-26
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
5.0 tigerFixed
Related Reports
Duplicate :  
Description

Name: nt126004			Date: 10/16/2002


FULL PRODUCT VERSION :
java version "1.4.1"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1-b21)
Java HotSpot(TM) Client VM (build 1.4.1-b21, mixed mode)

A DESCRIPTION OF THE PROBLEM :
It is only possible to use the javadoc inline tag @value
inside the documentation of the constant field. It should be
possible to use it everywhere and extend the syntax of this
tag to

{@value package.class#member  label}

The idea is to have the constant values available in every javadoc comment. 
This is just for convenience

Example:

public static final String SCRIPT_START = "<script>";
public static final String SCRIPT_END = "</script>";


Currently with the actual version, you have to navigate two times, click on 
the link for this method and click on the values link of the constant,
like this:

/**
 * Evaluates scripts given in the specified script string. 
 * Every script included in {@link #SCRIPT_START} and 
 * {@link #SCRIPT_END} is evaluated and the result is inserted 
 * in the string. 
 */
public String evalScripts(String script) {
}


Method doc I suggest

Just include the value (with a link to the constant)

/**
 * Evaluates scripts given in the specified script string. 
 * Every script included in {@value #SCRIPT_START} and 
 * {@value #SCRIPT_END} is evaluated and the result is inserted 
 * in the string. 
 */
public String evalScripts(String script) {

}

(Review ID: 164665) 
======================================================================
Here is an example from duplicate 4753737:

/**
 * Names the property file.
 */
public static final String NAME_OF_PROPERTY_FILE = "db2.properties";

/**
 * This method reads the properties out of {@value NAME_OF_PROPERTY_FILE}
 */
 public void readProperties() {
 ...
 }

/**
 * This method writes the properties into {@value NAME_OF_PROPERTY_FILE}
 */
 public void writeProperties() {
 ...
 }

So if I need to change the value of the constant to
"cloudscape.properties" I wouldn't have to redo all the Javadoc
comments. (I came to this while doing a lot of Search/Replace)!


Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger FIXED IN: tiger INTEGRATED IN: tiger tiger-b22
2004-06-14

PUBLIC COMMENTS I agree that the {@value} tag should be available everywhere. Why make the user navagate to the field to vi the constant value? The @value inline tag now takes an optional field name in the same format as the @see tag (<fully qualified class name>#<field name>). This enhancement request asks for a label parameter. I see no use for this. The label of the inline tag is the value of the constant. If @value is not used with the constant, it is linked ot the constant value so that the user will know where the value came from.
2004-06-10

EVALUATION This is very nearly a duplicate of 4753737: Allow {@value} to take field name arg and be used in any doc comment. The only difference is that this request allows for a label. One question: Is the given example a misuse of @value? That is, do we want to encourage the use of a value in a doc comment rather than its field name? ###@###.### 2002-10-16 The form of this tag would be: {@value package.class#member label} > ###@###.### wrote: > Question: Are these examples legitimate uses for displaying the value? > That is, are developers likely to be led to mistakenly use the value rather > than the field? > > Shall we allow/encourage developers to do this? ###@###.### wrote: I share your concerns. It isn't evil, but it's open to abuse. I'm not sure whether I'd do this. =========== I added an optional field name paramenter to the @value inline tag. I see no reason why we should not add this. It is inconvienent for the user to have to paste constant values in their documentation. This bug fix will be integrated with the doclet toolkit. ###@###.### 2003-05-07
2003-05-07