如何智能地修复 Eclipse 中的文档？

Posted 2023-03-31

【中文标题】如何智能地修复 Eclipse 中的文档？

【英文标题】：How to intelligently fix documentation in Eclipse?

【发布时间】：2012-10-07 22:31:15

【问题描述】：

回到我的 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？

【问题讨论】：

必须修改 Eclipse Java 编辑器才能做到这一点，所以我会拒绝。

您始终可以为 Eclipse 创建自己的插件，该插件将检查类中的所有方法，如果 javadoc 对应于参数、异常......然后让它为这些标签插入默认值。看到这个tutorial by Vogel...也许下次我无事可做，因为我倾向于在写完javadoc之后重构我的代码。

Eclipse JDT 在这个过程中也会有所帮助。

【参考方案1】：

不确定下面是不是你说的，但是由于eclipse有自己的JavaDoc Validator，你可以在下配置compile Warnings/Errors

窗口 -> 首选项 -> Java -> 编译器 -> JavaDoc。

根据您自己的需要激活缺少的 javadoc 标记并将警告级别设置为“警告”，只要您的 javadoc 与您的方法签名不同，编译器就会注意到您的更改并向您发出警告。要修复它，它提供了一个快速修复 (STRG+1)，您可以选择添加所有缺失的标签。此操作即使在正确的位置也会添加缺少的标签，而不会弄乱您的旧评论。

【参考方案2】：

Eclipse 也支持 JavaDoc 的“代码”完成。您不必键入hole 语句。您只需键入“@p”，CTRL+Space 将为您打印其余部分。或者更好的是，只写参数的名称，代码完成将添加其余部分。

这不是直接的捷径，但你可以更快地编写 javadoc，而不是从头开始编写所有内容。

@t (@throw) @r (@return) 等也是如此。

编辑您的评论：

您可以配置 Checkstyle，以自动检查您的课程。当您的方法具有未记录的参数或其他一些缺少的参数时，Checkstyle 将报告。 Checkstyle 还可以检查你的第一句话是否以'.'结尾。或不。你可以手动制定很多这样的规则。

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

【讨论】：

很好。但它没有做的是检测我何时有缺少文档的参数，缺少返回文档，缺少方法描述，缺少异常文档等......我尽我所能，但我只是人类。所以像 GhostDoc 这样的工具非常有用。

不正确！我们在公司中使用了这种机制，并且在所有这些情况下我都得到了问题标记。

嗨，马库斯。我的评论是对您最初的回答的回应。针对我的评论，您修改了答案。这个修改后的答案是准确的，也是我想要的。谢谢。

【参考方案3】：

http://jautodoc.sourceforge.net/ 也适用于 Luna 请到市场查询

【参考方案4】：

在典型评论位置（与 GhostDoc 相同的位置）上方键入 /** 将自动完成评论模板。

如果您使用重命名功能 (Shift+Alt+R) 更改变量的名称，那么 Eclipse 也会在所有正确位置更改名称，假设代码已编译。

这包括和评论您创建的链接

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

使用 Eclipse 的重命名功能重命名 myThing 或 MyThingClass 也会更新这些引用。

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

基本上，如果您要重构，请使用重构菜单 (Shift+Alt+T)。

【讨论】：

我尝试这样做，但有时会发生一些事情，例如另一个开发人员提交了没有以这种方式重构的版本控制的更改。虽然防止这种情况是理想的，但我真的在寻找一种方法来解决它当它发生时。

@JasonThompson 啊。我不知道这样做的方法，也许建议 PMD 和 CheckStyle 在办理登机手续时强制执行这些事情？同样，让负责检查半垃圾代码的开发人员遇到困难。它在这里工作。

【参考方案5】：

Checkstyle 已经被提及。我试过了，但它似乎让我的 Eclipse 变慢了很多（虽然 E4 juno，它以有一些糟糕的减速而闻名）。

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

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