United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4764045 javadoc inline tag {@value} should be available everywhere
JDK-4764045 : javadoc inline tag {@value} should be available everywhere

Details
Type:
Enhancement
Submit Date:
2002-10-16
Status:
Resolved
Updated Date:
2003-09-26
Project Name:
JDK
Resolved Date:
2003-09-26
Component:
docs
OS:
other,linux,windows_2000
Sub-Component:
doclet
CPU:
x86,generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0,1.4.1
Fixed Versions:
5.0 (tiger)

Related Reports
Duplicate:

Sub Tasks

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
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
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
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger

FIXED IN:
tiger

INTEGRATED IN:
tiger
tiger-b22


                                     
2004-06-14



Hardware and Software, Engineered to Work Together