Question

我肯定有一个相当常见的文档需求...

我正在实现一个相当大的Java库代码库，其中包含各种类，这些类旨在以适当的抽象级别向调用者/实现者公开。同时，代码库当然包含各种内部类，接口和其他抽象，库的用户无需知道这些抽象，以便使用API。

许多其他的API库都会犯错误，只需将所有内容都放入Javadocs中，然后通过猜测的一些组合，让用户知道他们实际需要处理哪些对象和实体作为调用者，推理，如果幸运的话，还有示例代码。

我不想处于相同的位置。我希望有一组“内部”Javadocs公开代码库的整个范围，以及一组“外部”Javadoc，旨在清楚地向开发人员传达他们实际需要用来获取他们的类的特性。完成工作。我不需要或想要用他们不需要看到或知道的各种内部抽象来混淆水域 - 他们没有必要知道它是如何在引擎盖下工作的，它只会混淆和误导它们，使得API学习过程非常低效。

我怎样才能做到这一点？是否有一个众所周知的'javadoc'参数组合，也许还有一些注释可以实现这一点？

非常感谢您的考虑！

Answer 1

假设您已遵循最佳实践并将内部类放在不同的包中，您可以使用公共API包名称作为命令行参数运行javadoc。

有关详细信息，请参阅javadoc command line synopsis。

（如果你还没有组织你的软件包来保持内部类不在API包中，你可能会有点痛苦......）

Answer 2

除了Stephen C的答案并使用javadoc工具之外，您还可以使用类似这样的内容确切地指定javadoc中出现的包（因此，如果Stephen C的注释不是逻辑组织的话，那就是他们的评论）：

假设您有5个类，并且只希望org.notprivate包中的类出现在Javadoc中：

org.notprivate.Foo
org.notprivate.Bar
org.notprivate.Stuff
org.notpublic.Things
org.notpublic.More

您可以使用以下内容：

javadoc -d target/api -source 1.6 -sourcepath src/main/java org.notprivate

这只是一个简单的例子，如果您需要指定每个类，您需要查看Stephen C提供的更详细的链接

为清晰起见，请在此处发布： Javadoc Documentation

Answer 3

我希望......一组“外部”Javadoc旨在清楚地向开发人员传达他们实际需要用来完成工作的类的特性。我不需要或想要用他们不需要看到或知道的各种内部抽象来混淆水域 - 他们没有必要知道它是如何在引擎盖下工作的，它只会混淆和误导它们，使得API学习过程非常低效。

鉴于这种愿望，或许Javadoc不是记录整个系统视图或向新开发人员提供“这是你需要知道的”类型信息的最佳方法吗？

我建议使用单独的指南/文档/ wiki /某些内容来补充您的Javadoc文件以提供元视图。

Answer 4

调用javadoc工具时可以使用一些额外的参数：

-public：仅显示公共类和成员。
-protected：仅显示受保护的公共类和成员。这是默认设置。
-package：仅显示包，受保护和公共类及成员。
-private：显示所有类和成员。

因此，使用这些选项，您可以生成内部使用的完整文档，并为您的客户提供仅包含公共界面的“轻量级”文档。

如果您正在使用Eclipse，则Javadoc向导会显示单选按钮以帮助您选择文档级别 - 默认情况下为“仅限公共字段”。

选择性API Javadocs

4 个答案: