Question

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

类似的东西：

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

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

Answer 1

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

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

Answer 2

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

您可以按照this thread中的建议使用@deprecated标记方法，然后在运行javadoc时使用选项-nodeprecated。

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

Answer 3

如果您使用的是Sun的JavaDocs工具，那就不行了。

他们有a feature request，但自1997年以来一直处于低优先级。

您可以编写自定义doclet来解决此问题，或使用第三方工具（DocFlex等）。

Answer 4

/**
 *  Don't use this method <br>
 *  <i>or all your data will be lost.</i>
 */
public void foo(){
    //...
}

好吧，使用更好的解释为什么用户不应该使用这种方法...
请记住，使用反编译器或反射找到任何（公共）方法并不困难。

用于禁用JavaDocs的注释

4 个答案: