如何从 Javadoc 中排除不推荐使用的公共方法？答案

【问题标题】：How to exclude deprecated public methods from Javadoc?如何从 Javadoc 中排除不推荐使用的公共方法？
【发布时间】：2011-01-06 12:11:41
【问题描述】：

我想为我的课程生成 javadoc。 “生成 Javadoc”命令为我提供了一个选项，可以为具有 Private/Package/Protected/Public 可见性的成员创建 Javadoc。但是有一些公共方法我不想包含在 Javadoc 中。如何为此 Javadoc 生成器准确指定要包含哪些成员/方法以及不包含哪些成员/方法？

（我用的是eclipse 3.4.2）

编辑：你们中的一些人问我想这样做的原因是什么。原因是我有一些我不想存在的方法，但我仍然需要它们来实现向后兼容性。我将它们标记为@deprecated，以便尝试使用它们的人会收到警告。但我不希望它们出现在 Javadoc 中。鉴于它们被标记为@deprecated，有没有办法将它们从 javadoc 中排除？

【问题讨论】：

您想要这样做的任何特殊原因？如果您想“隐藏”一个公共方法，它会向我建议您的实现已损坏。见这里：stackoverflow.com/questions/1928467/…
我同意杰森的观点……公开就是公开。
你不能向公众隐瞒什么是给公众的 :)
谢谢大家。我同意“公众就是公众”。但是我想排除的方法已被弃用。我不删除它们的唯一原因是为了向后兼容。我编辑了问题以提及这一点。
我认为不推荐使用的方法是最需要记录的方法，因此您可以告诉人们停止使用它们并改用whatever-new-method！

标签： java javadoc deprecated public-method

【解决方案1】：

你必须自己写Doclet。

【讨论】：

【解决方案2】：

所以你有一些出于某种原因必须公开的方法，但类用户真的不应该搞砸吗？

您可以将这种 JavaDoc 用于那些“隐藏”的公共方法：

 /**
  * !!! THIS METHOD IS NOT PART OF PUBLIC INTERFACE !!!
  * !!! DO NOT USE !!!
  */
 public void somethingThatShouldNotBeUsedByOutsiders()

我快速浏览了一下，似乎没有办法至少通过标准 JavaDoc tools 进行方法级别的排除。

【讨论】：

这让我想起了 DailyWTF 条目forums.thedailywtf.com/forums/p/3616/88501.aspx 当文档警告他们不要使用某些东西时，用户不会听。这很可悲，但却是真实的。

【解决方案3】：

正如 Software Monkey 所写，您可能必须编写自己的 Doclet。 example 几乎可以满足您的需求，ExcludeDoclet

【讨论】：

谢谢。但我想要的是排除方法，而不是类。我认为这个工具只能排除类。还有其他想法吗？
下载并更改它。这是一个示例（单击示例链接）。否则，请尝试developer.berlios.de/projects/padoclet

【解决方案4】：

那么，为什么javadoc -nodeprecated 不成功呢？

【讨论】：

看起来这是找我的正确方法。尽管 java @Deprecated 注解不会导致该方法被排除，但这似乎是 javadoc 中的一个错误，您必须在该方法的 javadoc 中使用 @deprecated 标记。
我想这就是我的答案。我不在电脑旁，所以明天我会检查一下，可能会接受你的回答。谢谢。
+1：当我回答时，他没有说他为什么要排除这些方法，否则我会提出同样的建议。