I just got tired of search/replace in JavaDoc parts and asked myself if the following is possible:
(I use JSP Syntax for the part that I don't know if it's posible)
publicstatic String insert ="this ist the insert";
/**
* Display here: <%=insert%>
*/
Any ideas!?
Yes, it is possible in 1.4.x (though the doc comment must go
before the declaration):
/**
* Display here: {@value}
*/
public static String insert = "this ist the insert";
In fact, a constant values page is automatically created
(as follows), so it's unnecessary to do the trick above:
http://java.sun.com/j2se/1.4/docs/api/constant-values.html
{@value} is documented at:
http://java.sun.com/j2se/1.4/docs/tooldocs/windows/javadoc.html#{@value}
-Doug Kramer
Javadoc team
Thanks - but I hoped to get a little bit more out of it.
I was looking for a way to customize parts of a series of Javadoc comments. Example:
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. (Like I said - I came to this while doing a lot of Search/Replace)!
I guess, as you didn't mention anything going in that direction, (and the documentation doesn't either) this is (yet) impossible.
Anyway thanks for the reply. And maybe you might want to add this functionality!? :-)
Sounds like a great idea. Thank you for this request.
I've submitted this as feature request 4753737:
stddoclet: Allow {@value} to take field name arg and be used in any doc comment
As is our convention, the format would be {@value name} with no colon.
Which will eventually show up (in a couple of days) at:
http://developer.java.sun.com/developer/bugParade/bugs/4753737.html
-Doug Kramer
Javadoc team
> Was this {@value variable} feature ever implemented?
> I really think is is a great idea and wish I could
> use it.
It has been added for 1.5. For 1.4 you can use this simple taglet:
import com.sun.tools.doclets.Taglet;
import com.sun.tools.doclets.standard.HtmlStandardWriter;
import com.sun.tools.doclets.standard.tags.AbstractInlineTaglet;
import com.sun.javadoc.*;
import java.util.Map;
public class MyValueTaglet extends AbstractInlineTaglet {
private static final String NAME = "my.value";
/**
* Return the name of this custom tag.
*/
public String getName() {
return NAME;
}
public boolean inField() {
return true;
}
public boolean inConstructor() {
return true;
}
public boolean inMethod() {
return true;
}
public boolean inOverview() {
return false;
}
public boolean inPackage() {
return false;
}
public boolean inType() {
return true;
}
public boolean isInlineTag() {
return true;
}
/**
* Register this Taglet.
*
* @param tagletMapthe map to register this tag to.
*/
public static void register(Map tagletMap) {
MyValueTaglet tag = new MyValueTaglet();
tagletMap.put(tag.getName(), tag);
}
public String toString(Tag tag, Doc doc, HtmlStandardWriter hsw) {
ClassDoc lookup = null;
if ( doc instanceof ClassDoc )
{
lookup = (ClassDoc)doc;
}
else if ( doc instanceof MemberDoc )
{
lookup = ((MemberDoc)doc).containingClass();
}
if ( lookup == null )
{
return "";
}
final String fieldName = tag.text();
final FieldDoc[] fields = lookup.fields();
for (int i = 0; i < fields.length; ++i)
{
if ( fieldName.equals( fields[i].name() ) )
{
final Object value = fields[i].constantValue();
return (value != null) ? value.toString() : "";
}
}
return "";
}
}
Note:
In order to get this to work project wide, you need to have full qualified names as tag text and use the RootDoc to locate the appropriate packages and classes.
