java - JAutodoc:getter 注释模板与默认注释行为合并

Question

我正在尝试配置 JAutodoc，以便生成仅包含 @returns 标记的 getter 注释，如下所示:

/**
 * @returns The non-null {@linkplain Foo foo} of this {@link IBar}.
 */
public Foo getFoo();

我已经配置了我的 getter 模板来生成这个:

但是，我的一般 JAutodoc 设置一定有问题，因为我得到的是我的模板和从方法名称解析的注释的混合体:

/**
 * Get foo.
 * @returns The non-null {@linkplain Foo foo} of this {@link IBar}.
 */
public Foo getFoo();

这些是我的设置:

我已从替换列表中删除“获取”替换，并取消选中“来自字段评论的字母”设置，如 this discussion 中的建议, 但它并没有产生明显的差异。我还尝试取消选中“从元素名称创建注释”设置，尽管我的示例 getter 是接口(interface)的一部分(在这种情况下没有元素可以从中获取注释)，但 JAutodoc 没有似乎并不关心这一点。

我还尝试在进行这些更改后重新启动 Eclipse，以防万一。到目前为止，没有任何效果。 getter 的注释行为几乎看起来像是硬编码的。有人可以解释一下吗？

Answer 1

长话短说

JAutodoc，以其目前的形式，不能做你想让它做的事。这是因为您要求的 Javadoc 不完整。

详情

(这很有趣，我希望你能欣赏你的努力:-)

在这种情况下，您要求 JAutodoc 创建不完整的 Javadoc。也就是说，您在 Javadoc 中不要求任何文档。 (顺便说一句，我个人觉得简单 setter/getter 的重复性也很烦人)。

JAutodoc 在内部进行的步骤是:

1. 应用您的模板，使评论看起来完全符合您的要求 - 暂时。

这是应用模板的代码。使用您的示例，下面的 member 参数是您的 getFoo 方法，并且由于您首次应用自动注释时代码中没有现有注释，因此 jdi 参数为空 (jdi.isEmpty() == true)。

应用模板后，text 看起来也完全符合您的要求。 text 像任何 Javadoc 注释一样被解析并返回。

来自net.sf.jautodoc.source.JavadocCreator:

public JavadocInfo applyTemplate(final IMember member, final JavadocInfo jdi) throws Exception {
    final JavadocInfo templateJdi = new JavadocInfo();
    final String text = JAutodocPlugin.getContext().getTemplateManager().applyTemplate(member,
            config.getProperties());
    if (text != null && text.length() > 0) {
        templateJdi.parseJavadoc(text);
    }
    return jdi.isEmpty() ? templateJdi : jdi.merge(templateJdi);
}

1. 现在从 applyTemplate 返回的 JavadocInfo 被传递给 createJavadoc。在 createJavadoc 中，代码检查是否有注释(不包括 @param、@return 等)。由于没有，它会尝试从可用信息中自动插入一些。简单地说，它只是取消了方法名称的驼峰式大小写，并将其作为注释。

来自 net.sf.jautodoc.source.JavadocCreator

public String createJavadoc(final IMethod method, final String indent, final String lineSeparator,
        final JavadocInfo jdi) throws JavaModelException {

    final List<String> text = jdi.getComment();
    if (text.isEmpty()) {
        if (config.isCreateDummyComment()) {
            if (method.isConstructor()) {
                text.add(Constants.JDOC_CONSTRUCTOR);
            }
            else if (method.isMainMethod()) {
                text.add(Constants.JDOC_MAIN);
            }
            else {
                String comment = CommentManager.createComment(config, method.getElementName(),
                        CommentManager.METHOD, true, true, CommentManager.FIRST_TO_UPPER);
                text.add(comment + Constants.DOT);
            }
        }
        else {
            text.add("");
        }
    }
    else {
        checkForDot(text);
    }

现在调用上面两个方法的代码是这样的:

来自net.sf.jautodoc.source.SourceManipulator.addJavadoc(IMember):

if (config.isCreateDummyComment()) {
    jdi = javadocCreator.applyTemplate(member, jdi);
}
newJavadoc = javadocCreator.createJavadoc((IMethod) member, indent, lineDelimiter, jdi);

正如您从这些代码片段中看到的，应用模板和创建评论部分(您不想要的!)都由相同的 if 语句 config.isCreateDummyComment() 控制。该 if 语句连接到 Create comment from element name 选项。

例子

这个问题不会发生，因为该方法是一个 setter/getter ，但适用于任何地方。假设您有这段代码:

/**
 * @param myFirstParam this is important and I documented it
 */
public int doThisAndThat(int myFirstParam, int anotherParamHere) {
    return 0;
}

然后将 JAutodoc 应用于它(使用 Complete existing Javadoc)然后您将得到:

未设置从元素名称创建注释:

/**
 * 
 *
 * @param myFirstParam this is important and I documented it
 * @param anotherParamHere 
 * @return 
 */
public int doThisAndThat(int myFirstParam, int anotherParamHere) {
    return 0;
}

使用 Create comment from element name 设置:

/**
 * Do this and that.
 *
 * @param myFirstParam this is important and I documented it
 * @param anotherParamHere the another param here
 * @return the int
 */
public int doThisAndThat(int myFirstParam, int anotherParamHere) {
    return 0;
}

获取源代码

我找不到任何常见嫌疑人(github 等)的来源，但可以在这里下载:http://sourceforge.net/projects/jautodoc/files/jautodoc/1.13.0/

因此，如果您愿意，您可以编辑源代码并重建您的插件。或者向开发人员提交功能请求。

总结

JAutodoc，以其目前的形式，不能做你要求它做的事。然而，这本质上是设计使然，因为如果您说您想要自动Create comment from element name(内部称为 Create Dummy Comment)，那么您需要为您创建完整的 Javadoc。

最后，请记住，如果没有注释，则方法摘要表中不会出现任何内容，您生成的 Javadoc 看起来不完整。