4

我正在尝试配置 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();

这些是我的设置：

在此处输入图像描述

我已经从替换列表中删除了“获取”替换，并且按照本次讨论中的建议取消了“字段注释中的其他”设置，但它并没有产生明显的差异。我还尝试取消选中“从元素名称创建评论”设置，尽管我的示例 getter 是接口的一部分（在这种情况下，没有元素可以从中获取评论），但 JAutodoc 似乎并不关心这一点.

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

4

1 回答 1

4

TL;博士

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

细节

（这很有趣，我希望你感谢你的努力:-)

在这种情况下，您要求 JAutodoc 创建不完整的 Javadocs。即，您要求在 Javadoc 中不提供任何文档。（我个人觉得简单吸气剂的重复性也很烦人）。

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. 现在JavadocInfo返回的那个被applyTemplate传递给createJavadoc. 在createJavadoc代码中检查是否有注释（不包括@params @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选项。

例子

这个问题没有发生，因为该方法是一个吸气剂，但适用于任何地方。假设您有这段代码：

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

然后你将 JAutodoc 应用到它（使用Complete existing Javadoc）然后你得到：

未Create comment from element name设置：

/**
 * 
 *
 * @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。

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

于 2015-10-24T21:46:34.100 回答