编辑 Eclipse Javadoc ${tags} 变量

Question

版本：Luna Service Release 2 (4.4.2)

我通常使用“/**”方法在我的方法中插入 Javadoc。 Eclipse 为所有参数插入 @param，为所有可抛出对象插入 @throws，以及一个 @return。但是 @return 从来没有附加类型。它看起来像这样：

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

第一个问题是：Eclipse 中是否有一个开关使其在添加 Javadoc 时自动插入方法 return 类型？

没找到，所以查了一下：preferences->java->code style->code templates->Methods

在该模板上，我看到一个变量 ${tags}。该变量生成上面显示的 Javadoc。

第二个问题是：有没有办法编辑 ${tags} 以包含附加到 @return 的变量 ${return_type}，它是由 ${tags} 生成的？

我希望能够键入 /**<enter> 并让 Eclipse 自动创建以下 Javadoc：

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

Answer 1

根据您的问题，Eclipse 中（目前）还没有允许您修改它的配置。那是因为 javadoc 中的注释必须抱怨自动生成类 javadoc HTML 的工具。如果允许更改它，javadoc 工具也应该有一个配置来理解该修改。

您不必担心这一点，因为此标记 @return 是针对 javadoc 生成的。生成项目 javadoc 后，您将看到每个方法都具有 return 类型（在生成的 html 中）。该标签用于方法结果的特定描述。

以这个方法为例：

/**
 * 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;
}

当您在 Eclipse 中将鼠标指针停在该方法上时，它将显示：

注意图像上该文档的第一行。它说：String Foo.getSomeAttribute()

当您通过 javadoc 工具或类似 Maven 的其他工具生成 Javadoc 时，它将生成所有 HTML 文件，其中包含类的所有 javadoc 和方法摘要会像这样(String class)

您可以在 "Modifier and type" 列中看到方法的 return 类型。如果您查看其中一种方法的源代码，例如图像 charAt(int index) 中的第一个方法，您会发现 @return 标记中没有类型。

/**
 * 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];
}

希望对您理解该标签有所帮助。

Answer 2

${tags} 变量在 Eclipse 中似乎不可编辑。通过一些代码后，这里有一个 link 到 class 负责解析变量。具体来说 insertTag 方法：

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$
        }
    }

    ...

请注意，无法附加 return 类型。模板中只插入了@return。

至少有一种非常 hacky 的方法可以做到这一点。您仍然可以通过转至 Window -> 首选项 -> Java -> 代码样式 -> 代码模板 -> 评论 并选择编辑编辑评论模板。然后您可以将模板更改为：

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

有关可用变量，请参阅 http://help.eclipse.org/mars/topic/org.eclipse.jdt.doc.user/concepts/concept-template-variables.htm。

但这会导致添加两个 @return 评论。正如另一个答案中提到的，不需要添加 return 类型，因为 Javadoc 生成器可以自动确定 return 类型。如果您正在使用其他工具解析评论，上述变通办法可以解决问题。

Answer 3

您是否尝试过 jautodoc 插件？看看它可能比 alt-shift-j 内置的 eclipse

更有帮助 you.its

http://jautodoc.sourceforge.net/

编辑 Eclipse Javadoc ${tags} 变量

Editing Eclipse Javadoc ${tags} Variable

java

eclipse

javadoc