如何在Eclipse中智能修复文档？

Question

我以前使用C#时候，很喜欢使用一款名为“GhostDoc”的Visual Studio扩展程序。现在作为Java开发人员，我使用Eclipse。虽然我可以没有推断性文档，但我希望能够智能地"修复"我的文档。例如，假设我有以下方法：

/**
 * Gets a collection of {@link Foo} objects
 * @param bar The bar level
 * @param baz The bazziness
 */
public Collection<Foo> getFoos(int bar, int baz)
{
    // Do something cool
}

在开发的后期，我意识到允许方法的使用者传入一个qux值会很有用。不仅如此，将其作为第一个参数是最合理的选择。此外，我还将让该方法抛出非常有用的FooBarException异常。现在我的方法看起来像这样：

/**
 * Gets a collection of {@link Foo} objects
 * @param bar The bar level
 * @param baz The bazziness
 */
public Collection<Foo> getFoos(String qux, int bar, int baz) throws FooBarException
{
    // Do something cool
}

作为一个优秀的开发者，我希望我的JavaDoc能够反映出我的修改。在GhostDoc中，我可以按下我的文档快捷键，它会添加新内容而不会干扰旧内容。但是在Eclipse中，它会呈现一整套新的JavaDoc，我必须复制粘贴一大堆东西。有什么方法可以自动将新的@param、@exception和缺失的@returns参数放入我的JavaDoc中，而不会丢失我当前已有的JavaDoc？

- Jason Thompson

---

Eclipse Java编辑器需要进行修改才能实现这一点，所以我的答复是不行的。 - Gilbert Le Blanc

你可以为Eclipse创建自己的插件，检查类中的所有方法，如果javadoc与参数、异常相对应，则插入这些标签的默认值。参见Vogel的教程……也许下次我没事干的时候会做一下，因为我写完javadoc后往往会重构我的代码。 - knownasilya

Eclipse JDT 也可以帮助完成这个过程。 - knownasilya

Answer 1

不确定以下是否符合您的意思，但由于Eclipse具有自己的JavaDoc验证器，您可以在

窗口->首选项->Java->编译器->JavaDoc下配置编译警告/错误。

通过激活自己需要的缺失的javadoc标签并将警告级别设置为“warning”，编译器将注意到您的更改并给出警告，一旦您的javadoc与您的方法签名不同。要修复它，它提供了一个快速修复（STRG+1），您可以选择添加所有缺失的标签。此操作将在正确的位置添加缺少的标签，而不会干扰以前的注释。

- crusam

Answer 2

Eclipse支持对JavaDoc的"代码"自动补全。您不必输入完整语句，只需键入"@p"，然后按下CTRL+空格，剩余部分将自动打印出来。或者更好的方法是，只需编写参数名称，代码自动补全将添加其余部分。

这不是直接的快捷方式，但可以更快地增强javadoc，而不必从头开始编写所有内容。

@t（@throw）@r（@return）等也是如此。

您可以配置Checkstyle以自动检查您的类。当您的方法具有未记录的参数或其他缺失参数时，Checkstyle会报告。Checkstyle还可以检查您的第一句话是否以'.'结尾。您可以手动设置许多此类规则。

Checkstyle将在您的Java代码编辑器和问题视图中添加问题标记。因此，您可以轻松找到具有Javadoc问题的代码行。

- Markus Lausberg

---

很好。但它无法检测到我缺少参数文档、返回文档、方法描述、异常文档等情况...我尽力了，但毕竟只是人。因此，像GhostDoc这样的工具非常有用。 - Jason Thompson

那不正确！我们公司使用这种机制，在所有这些情况下我都会得到问题标记。 - Markus Lausberg

嗨 Markus。我的评论是针对你最初的回答的。在回应我的评论后，您修改了您的答案。这个修改后的答案是准确的，也是我所需要的。谢谢。 - Jason Thompson

Answer 3

在典型的注释位置（与GhostDoc相同的位置）输入 /** 将自动完成注释的模板。

如果您使用重命名功能（Shift+Alt+R）更改变量名称，则Eclipse也会在所有正确的位置更改名称，假设代码可以编译。

这包括您制作的任何注释链接。

/**
 *
 * My funky method
 *
 * @param myThing
 *         myThing is of type {@link MyThingClass}
 */
 public void myMethod(MyThingClass myThing) {}

使用Eclipse的重命名功能来重命名myThing或MyThingClass，将同时更新这些引用。

同样地，使用“更改方法签名”功能也会更新您的注释。

基本上，如果您要进行重构，请使用重构菜单（Shift+Alt+T）。

- BanksySan

---

我尝试做到这一点，但有时会发生一些事情，比如另一个开发人员提交了未按此方式重构的版本控制更改。虽然防止这种情况是理想的，但当它发生时，我真的在寻找一种解决方法。 - Jason Thompson

@JasonThompson 啊。我不知道有什么方法可以做到这一点，也许可以推荐使用PMD和CheckStyle来强制执行这些检查？同样，对于提交半吊子代码的开发人员要严格要求。这里可以正常工作。 - BanksySan

Answer 4

http://jautodoc.sourceforge.net/ 也适用于Luna版本 请在市场中检查

- Ram Ghadiyaram

Answer 5

Checkstyle已经被提到过了。我试过了，但它似乎让我的Eclipse变得非常缓慢（尽管是E4 Juno，这是众所周知的一些严重减速问题）。

Google CodePro做得更好，所以我现在使用它。

当然，您也可以启用JavaDoc警告。

- Erich Schubert