选择性 API Javadocs

问题描述 投票：0回答：4

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

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

许多其他 API 库都犯了这样的错误：简单地将所有内容都扔到 Javadoc 中，并让用户通过猜测、推理、如果幸运的话，还可以提供示例代码。

我不想处于同样的境地。 我希望有一个“内部”Javadoc 集来公开代码库的整个范围，以及一个“外部”Javadoc 集，旨在清楚地向开发人员传达他们实际需要使用的类的特征，以获取他们的代码。完工。 我不需要或不想用他们不需要看到或了解的各种内部抽象来搅浑水——他们不需要知道这一切在幕后是如何运作的，这只会让他们感到困惑和误导，导致 API 学习过程非常低效。

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

java annotations documentation javadoc
4个回答
3
投票

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

javadoc
。

请参阅 javadoc 命令行概要 了解更多详细信息。

（如果您没有组织包以将内部类排除在 API 包之外，您可能会遇到一些痛苦...）

1
投票

除了 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 文档

0
投票

我想要......一组“外部”Javadoc，旨在向开发人员清楚地传达他们完成工作实际需要使用的类的特征。我不需要或不想用他们不需要看到或了解的各种内部抽象来搅浑水——他们不需要知道这一切在幕后是如何运作的，这只会让他们感到困惑和误导，导致 API 学习过程非常低效。

考虑到这种愿望，也许 Javadoc 不是记录整个系统视图或向新开发人员提供“这是您需要了解的”类型信息的最佳方法？

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

-1
投票

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

  • -public ：仅显示公共类和成员。
  • -protected ：仅显示受保护的公共类和成员。这是默认值。
  • -package ：仅显示包、受保护和公共类和成员。
  • -private ：显示所有类和成员。

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

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

最新问题
© www.soinside.com 2019 - 2024. All rights reserved.