编辑Eclipse Javadoc $ {tags}变量

Question

Version: Luna Service Release 2 (4.4.2)

I typically use the "/**" method to insert Javadoc on my methods. Eclipse inserts @param for the all the args, @throws for all the throwables, and a @return . However the @return never has a type appended to it. It looks like this:

/**
 * 
 * @param criteria
 * @param filters
 * @return
 */
protected static String 
          getColumnNameFromCriteria(SelectedCriteria criteria, List<SelectionFilter> filters)

The first question is: is there a switch somewhere in Eclipse to make it automatically insert the method return type when adding Javadoc?

I could not find one, so I looked up: preferences->java->code style->code templates->Methods

On that template I see a variable ${tags} . That variable is what generates the Javadoc shown above.

The second question is: is there a way to edit ${tags} to include the variable ${return_type} appended to @return that is generated by ${tags} ?

I want to be able to type /**<enter> and have Eclipse automatically create the following Javadoc:

/**
 * 
 * @param criteria
 * @param filters
 * @return String 
 */
protected static String 
          getColumnNameFromCriteria(SelectedCriteria criteria, List<SelectionFilter> filters)

Answer 1

Have you tried jautodoc plugin? have a look in to it may be it will help you.its better than eclipse built in alt-shift-j

http://jautodoc.sourceforge.net/

Answer 2

As per your question, there is no configuration in Eclipse (yet) that allows you to modify this. That is because the comments in javadoc must complain with the tool that automatic generates the classes javadoc HTML. If one was allowed to change that, the javadoc tool should also have a configuration to understand that modifications.

You don't need to worry about that since this tag @return is meant to a javadoc generation. Once you generate your project javadoc you will see that every method will have the return type (in the generated html). That tag is for a specific DESCRIPTION of the result of method.

Take this method exmaple:

/**
 * This is an example of a documentation of a method with a return type.
 * Note that there isn't a type on the `@return` tag
 * 
 * @return the someAttribute
 */
public String getSomeAttribute() {
    return someAttribute;
}

When, in Eclipse, you stop mouse pointer over this method it will show this:

Pay attention to the very first line of that docs on the image. It says: String Foo.getSomeAttribute()

When you generate the Javadoc via javadoc tool or another tool like Maven it willl generate all HTML files with all javadocs of your classes and the Method summary will be like this one ( String class )

You can see at the "Modifier and type" column the return type of the methods. If you look at the source code of one of those methods like the first one in the image charAt(int index) you wil see that there is no type in the @return tag.

/**
 * Returns the <code>char</code> value at the
 * specified index. An index ranges from <code>0</code> to
 * <code>length() - 1</code>. The first <code>char</code> value of the sequence
 * is at index <code>0</code>, the next at index <code>1</code>,
 * and so on, as for array indexing.
 *
 * <p>If the <code>char</code> value specified by the index is a
 * <a href="Character.html#unicode">surrogate</a>, the surrogate
 * value is returned.
 *
 * @param      index   the index of the <code>char</code> value.
 * @return     the <code>char</code> value at the specified index of this string.
 *             The first <code>char</code> value is at index <code>0</code>.
 * @exception  IndexOutOfBoundsException  if the <code>index</code>
 *             argument is negative or not less than the length of this
 *             string.
 */
public char charAt(int index) {
    if ((index < 0) || (index >= value.length)) {
        throw new StringIndexOutOfBoundsException(index);
    }
    return value[index];
}

I hope it helps you to understand that tag.

Answer 3

The ${tags} variable doesn't seem to be editable in Eclipse. After going through some of the code, here's a link to the class responsible for resolving the variable. Specifically the insertTag method:

private static void insertTag(IDocument textBuffer, int offset, int length, String[] paramNames, String[] exceptionNames, String returnType, String[] typeParameterNames, boolean isDeprecated,
        String lineDelimiter) throws BadLocationException {
    IRegion region= textBuffer.getLineInformationOfOffset(offset);
    if (region == null) {
        return;
    }
    String lineStart= textBuffer.get(region.getOffset(), offset - region.getOffset());

    StringBuffer buf= new StringBuffer();
    for (int i= 0; i < typeParameterNames.length; i++) {
        if (buf.length() > 0) {
            buf.append(lineDelimiter).append(lineStart);
        }
        buf.append("@param <").append(typeParameterNames[i]).append('>'); //$NON-NLS-1$
    }
    for (int i= 0; i < paramNames.length; i++) {
        if (buf.length() > 0) {
            buf.append(lineDelimiter).append(lineStart);
        }
        buf.append("@param ").append(paramNames[i]); //$NON-NLS-1$
    }
    if (returnType != null && !returnType.equals("void")) { //$NON-NLS-1$
        if (buf.length() > 0) {
            buf.append(lineDelimiter).append(lineStart);
        }
        buf.append("@return"); //$NON-NLS-1$
    }
    if (exceptionNames != null) {
        for (int i= 0; i < exceptionNames.length; i++) {
            if (buf.length() > 0) {
                buf.append(lineDelimiter).append(lineStart);
            }
            buf.append("@throws ").append(exceptionNames[i]); //$NON-NLS-1$
        }
    }

    ...

Notice that there is no way to append the return type. Only @return is inserted in the template.

There is at least a very hacky way to do it. You can still update the template by going to Window -> Preferences -> Java -> Code Style -> Code Templates -> Comments , and selecting Edit to edit the comment template. You can then change the template to:

/**
 * ${tags}
 * @return ${return_type}
 */

See http://help.eclipse.org/mars/topic/org.eclipse.jdt.doc.user/concepts/concept-template-variables.htm for available variables.

But this causes two @return comments to be added. As mentioned in the other answer, adding a return type is not needed as the Javadoc generator can automatically determine the return type. If you're parsing the comments in some other tool, the above workaround could solve it though.