如何从 javadoc Ant 任务的结果中排除特定的方法/构造函数?

2022-09-02 23:45:48

我正在使用由Ant任务生成的javadocs来记录Web服务,并且我想从输出中排除一些构造函数。我该怎么做?javadoc


答案 1

对于公共方法,没有办法做到这一点。标准做法(即使在相当多的JDK类中)是指示方法或构造函数不是供公众使用的。

计划将来添加@exclude标记

@exclude - 用于从 Javadoc 生成中排除 API。程序员会用@exclude标记类、接口、构造函数、方法或字段。标签的存在将导致 API 从生成的文档中排除。标记后面的文本可以解释排除的原因,但 Javadoc 会忽略它。(以前作为@hide提出,但术语“隐藏”更适合运行时动态显示/隐藏功能。有关更多讨论,请参阅开发人员连接中的功能请求 #4058216


答案 2

从文档中排除一些公开的内容,难道不就是“通过晦涩实现安全性”(或者更确切地说,“通过晦涩的文档”)的变体吗?如果构造函数是代码 API 的一部分,则可供他们使用。如果他们发现并使用它,那是他们的错吗(因为你首先把它公之于众)?

如果您可以更改构造函数的可见性或完全删除它,我会这样做。如果无法从 API 中删除它,请在 Javadoc 中为构造函数说明它不适合通过 Web 服务使用。这样,您就与 API 的用户建立了合同,通知他们不要使用它。

最好记录它不应该被使用,而不是根本不记录它(如果它是公开的)。不记录它会增加无意中使用它的风险,然后当您更改实现时,使用它的客户端代码会中断。


推荐