用于禁用JavaDocs的注释

Question

是否有注释声明某个方法不会包含在JavaDocs中,即使它是公开的？

就像是:

@nojavadocs
public void foo(){
//...
}

---

PS我理解这里关于API的观点,但这些方法只是"不受支持".它们可以工作(并且必须公开才能从其他软件包访问),但是当我们的功能与支持的使用场景无关时,我们不想打扰它们并回答有关如何使用它们的问题.好的设计可能意味着将它们移动到另一个类,但它们逻辑上引用了类中的数据.

Answer 1

我想到你想要这样做的唯一原因是在某种意义上"隐藏"这个方法,如果只是在文档方面.如果你这样做,你就会将文档设计为"破坏",因为文档在过时并且不再准确反映类的功能时会被破坏.由于该方法仍然是公共API的一部分,所以无论如何你都不会真正隐藏它.

如果您希望方法在类或少数用户之外未使用,请将其设为私有或打包.如果这很不方便而且必须是公开的,我只是非常清楚地记录了它的使用限制,可能有一个命名约定(例如,python这样做,有下划线包围的实体名称,你可以看到但是意味着比公共API更多地是类实现的一部分)

Answer 2

是的......但不是很好（拥有不是真正“公共”的公共方法并不是一个很好的设计实践）。

您可以按照此线程中给出的建议，并@deprecated在运行 javadoc use option 时使用then标记方法-nodeprecated。

编辑：正如其他人所指出的，这不是一个理想的行动方案。这将解决您的问题，但您确实需要重新思考为什么要隐藏该方法——给定代码的编译版本，有人仍然可以看到您的函数；将它隐藏在文档中实际上并没有隐藏方法。我真的想在这里强调 qualifiers private，public并且protected具有您应该考虑和有效利用的含义。没有所谓的“隐藏”public方法。

Answer 3

如果您使用的是 Sun 的 JavaDocs 工具，则不会。

他们有一个功能请求，但自 1997 年以来它一直处于低优先级。

您可以编写自定义 doclet 来克服这个问题，或者使用第三方工具（DocFlex 等）。