JavaDoc：仅记录用户应该使用的框架中的公共方法？答案

【问题标题】：JavaDoc: document only the public methods in a framework that users are supposed to use?JavaDoc：仅记录用户应该使用的框架中的公共方法？
【发布时间】：2015-08-14 08:17:01
【问题描述】：

由于框架的需要，框架通常需要包含具有公共方法的类；使用框架的用户实际上不应该调用它们。

例如，一个类可能有一个公共构造函数，因此另一个包中的工厂可以实例化它，但用户总是应该使用工厂，而不是直接使用构造函数。

我希望 JavaDoc 只发出关于用户应该调用的那些方法的文档，而不是其他方法。所以在这个例子中，它应该记录工厂方法，而不是公共构造函数。

当然，JavaDoc 本身不知道哪个是哪个，所以我认为“公共”方法可以使用一些注释进行注释，例如 @SupportedAPI，而 JavaDoc 只会在这些方面吐出文档。（这将有助于清楚地标记哪些方法有望保持稳定。）

可以配置 JavaDoc 来执行此操作吗？

【问题讨论】：

为什么不简单地定义一个干净的 API，为那些应该由用户使用的方法提供接口并用 JavaDoc 记录这些方法？实现此接口的类将自动重用接口上声明的文档，因此没有进一步的开销
因为不是所有的接口都是供用户使用的，因为有些类是供用户使用的（例如工厂）
然后将那些不打算由用户使用的类隐藏在包层次结构中，并提供用户可以用来与您的框架交互的方式。向用户隐藏每个细节不应该是框架的工作。如果（有经验的）用户想要了解内部细节，让他们这样做 - 如果你坚持不惜一切代价隐藏内部细节，你需要重新安排你的包和类结构。
我正在寻找一种方法来“标记”那些“普通”用户在经常使用框架时应该使用的那些类/接口/方法，这正是您提到的原因，并生成两个版本的JavaDoc。但遗憾的是我找不到这样做的方法。
也在我的愿望清单上，4年后！

标签： java javadoc maven-javadoc-plugin

【解决方案1】：

我也很想念这个。我有一个分成包的 Java 库；其中的一些方法是公开的，只是因为它们需要被库的其他包使用，而不是被库的用户使用。

我一直在使用 yDoc——Javadoc 的 doclet 扩展——向类和方法添加 @y.exclude 标记，以防止它们被记录。这远不是一个完美的解决方案，但仍然比默认的 Javadoc 更好。

看起来 yDoc 已重命名为 yWorks。似乎还有免费的社区版：https://www.yworks.com/products/ydoc

【讨论】：