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();

这些是我的设置：

我已从替换列表中删除了'get'替换，并取消选中this discussion中建议的'etter from field comment'设置，但它没有明显区别。我还尝试取消选中“从元素名称创建注释”设置，尽管我的示例getter是接口的一部分（在这种情况下没有元素来获取注释），但是JAutodoc没有好像在乎这件事。

我还尝试在完成每个更改之后重新启动Eclipse，以防万一重要。到目前为止，没有任何工作。几乎看起来好像getter的评论行为是硬编码的。有人可以对此有所了解吗？

Answer 1

TL; DR

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

详细

（这很有趣，我希望你欣赏这些努力： - ）

这是您要求JAutodoc创建不完整的Javadoc的情况。即你要求Javadoc没有文件。（我个人觉得简单的getter上的重复性太烦人了）。

JAutodoc内部的步骤是：

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

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

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

来自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);
}

现在，JavadocInfo返回的applyTemplate已传递给createJavadoc。在createJavadoc中，代码会检查是否有评论（@param除外，@return等）。由于没有，它会尝试从可用信息中自动插入一些。简单地说，它只是un-camel-cases方法的名称并作出评论。

来自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选项。

实施例

这个问题没有发生，因为该方法是一个getter，但适用于所有地方。假设你有这段代码：

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

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

JAutodoc：getter评论模板与默认评论行为

1 个答案:

TL; DR

详细

实施例

获取源

结论