java - 禁用 JavaDocs 的注解

Question

是否有注释声明某个方法即使是公共(public)的也不会包含在 JavaDocs 中？

类似于:

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

---

附言我理解这里关于 API 的要点，但这些方法只是“不受支持”。它们可以工作(并且必须公开才能从其他包访问)，但我们不想费心记录它们并在它们的功能与支持的使用场景无关时回答有关如何使用它们的问题。好的设计可能意味着将它们移动到另一个类，但它们在逻辑上引用了类中的数据。

Answer 1

我能想到您想要这样做的唯一原因是在某种意义上“隐藏”该方法，如果只是在文档方面的话。如果您这样做了，那么您将把文档设计为“损坏”，即当文档过时并且不再准确反射(reflect)类所做的事情时，文档就会损坏。由于该方法仍然是公共(public) API 的一部分，因此您并没有真正隐藏它。

如果你想让一个方法在类之外或者少数用户不用，就把它设为private，或者package。如果这不方便并且它必须是公开的，我会非常清楚地记录它的使用限制，可能有一个命名约定(例如，python 这样做，有实体名称被下划线包围，你可以看到但是意味着比公共(public) api 更多地成为类实现的一部分)