代码之家 › 专栏 › 技术社区 › Alex Balashov

选择性api javadocs

javadoc annotations documentation api java

Alex Balashov · 技术社区 · 16 年前

我肯定有一个相当常见的文件需要…

我正在执行一个相当大的Java库代码库,除其他事项外,它还希望在适当的抽象级别上暴露给调用方/实现者。同时,当然,代码库包含各种内部类、接口和其他抽象,这些抽象是库用户使用api所不需要知道的。

很多其他的api库都犯了这样一个错误:把所有东西都扔进javadocs中,让用户通过一些猜测、推断和(如果幸运的话)示例的组合来确定哪些对象和实体实际上需要作为调用者来处理。代码。

我不想处于同样的位置。我希望有一个“内部”的javadocs集,它公开了整个代码库的范围,还有一个“外部”的javadocs集,旨在向开发人员清楚地传达他们完成工作所实际需要使用的类的特性。我不需要也不想用他们不需要看到或知道的各种内部抽象来搅浑这片水域——他们不需要知道这些抽象在幕后是如何工作的,这只会混淆和误导他们,导致一个非常低效的API学习过程。

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

非常感谢您的考虑!

4 回复 | 直到 16 年前

Stephen C 16 年前

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

参考 javadoc command line synopsis 更多细节。

(如果您没有组织包以将内部类排除在api包之外,您可能会遇到一些麻烦…)

edwardsmatt 16 年前

除了Stephen C的回答和使用 javadoc 工具,您可以使用以下方法指定javadoc中出现的包(因此stephen c对“pain”的评论,如果它们不是逻辑组织的话):

假设您有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

matt b 16 年前

我想要…一组“外部”的javadocs,目的是向开发人员清楚地传达他们实际需要用来完成工作的类的特性。我不需要也不想用他们不需要看到或知道的各种内部抽象来搅浑这片水域——他们不需要知道这些抽象在幕后是如何工作的,这只会混淆和误导他们,导致一个非常低效的API学习过程。

考虑到这种需求,也许javadoc不是记录整个系统视图或向新开发人员提供“以下是您需要知道的”类型信息的最佳方法?

我建议用单独的guide/document/wiki/something来补充javadoc文件,以提供元视图。

-1

Olivier Croisier 16 年前

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

-public:仅显示公共类和成员。
-受保护:仅显示受保护的类和公共类以及成员。这是默认设置。
-package:仅显示package、protected和public类及成员。
-私有:显示所有类和成员。

因此,有了这些选项,您可以生成一个完整的内部使用文档,并提供一个“轻”文档,其中只有您的客户的公共接口。

如果您使用的是eclipse,javadoc向导会显示单选按钮来帮助您选择文档级别,默认情况下,文档级别是“仅公共字段”。