javadoc 子集/java 库组织

Question

我自己从来没有运行过javadoc（无论是在命令行还是ant的javadoc任务 ；我将使用 ant）——我需要为我编写的库生成 javadoc。

问题是我的java库被组织成几个包，并且Java中没有办法使类在库内公开但不向外界公开，所以我有一堆public 从实现的角度来看，而不是从库的角度来看语义的角度。

所以我需要弄清楚两件事。

1. （短期解决方案）有没有办法为我的库的使用者使用的类/接口/方法的特定子集生成 javadoc？

2. 我如何重组图书馆以确保公共意味着公共？

Answer 1

如果您可以通过包将公共公共与内部公共类分开（即有一些包包含您的库用户所需的所有公共类，并且没有其他公共类）类），然后仅在这些包上运行 Javadoc。

Javadoc 的工作原理是提供要使用的包的列表（以及用于查找这些包的源路径），并仅生成这些包的文档。

对于 Ant，情况会稍微复杂一些，因为使用 javadoc 任务的最简单方法是使用 ，默认情况下会采用给定目录中的所有包。

这是一个只有一个包的示例：

  <target name="javadoc">
    <javadoc destdir="${javadoc}"
         encoding="US-ASCII"
         charset="UTF-8"
         docencoding="UTF-8"
         use="yes"
         windowtitle="JSch API"
             sourcepath="${src}"
         >
      <arg value="-notimestamp" />
      <package name="com.jcraft.jsch" />
      <doctitle>JSch – Java Secure Channel ${version}</doctitle>
      <bottom>This is an inofficial Javadoc created by Paŭlo Ebermann.
    Have a look at the <a href="http://www.jcraft.com/jsch/">official homepage</a>.
      </bottom>
      <link href="http://download.oracle.com/javase/6/docs/api/" />
    </javadoc>
  </target>

您可以查看结果，但它是事实上这不是一个很好的例子，因为这里的主包包含许多不供消费者使用的类。

---

如果您处于像 JSch 这样的情况，即您无法通过包将 public public 与内部 public 类分开，因为您有包含公共类型和私有类型的包，还有办法做到这一点。 Javadoc 还支持不提供包名称，而是提供单个文件名作为参数。由于我刚刚花了一些时间弄清楚如何使用 ant 执行此操作，因此生成的 ant 目标代码如下：

  <target name="simple.javadoc">
    <javadoc destdir="${simple.javadoc}"
             encoding="US-ASCII"
             charset="UTF-8"
             docencoding="UTF-8"
             use="yes"
             windowtitle="simple JSch API"
             excludepackagenames="*"
             sourcepath="${src}"
             >
      <arg value="-notimestamp" />
      <sourcefiles>
        <resourcelist encoding="US-ASCII">
          <file file="simpleclasses.list" />
        </resourcelist>
      </sourcefiles>
      <doctitle>JSch – Java Secure Channel ${version} (simplified version)</doctitle>
      <bottom>This is a simplified version of the <a href="http://epaul.github.com/jsch-documentation/javadoc/">inofficial Javadoc</a> created by Paŭlo Ebermann.
        Have a look at the <a href="http://www.jcraft.com/jsch/">official homepage</a>.
      </bottom>
      <link href="http://download.oracle.com/javase/6/docs/api/" />
    </javadoc>
  </target>

源文件列于 simpleclasses.list 此处，使用 resourcelist。我认为带有 includesfile=... 的简单文件集也可以工作（并且它也将允许模式而不是简单的列表）。

我必须搜索很长一段时间的重要一点：如果您提供 sourcepath 属性，但不提供任何 packagenames 属性或 子元素，除了提到的文件之外，ant 将自动提供“所有包”默认值，这会导致不排除任何内容。 （我们希望此处的 sourcepath 允许从未记录的类继承文档。）因此，我们还必须提供 excludepackagenames="*"，这样现在只有 < code>元素定义要记录的内容。

结果现在看起来好多了，感谢您的提问。

Answer 2

首先，有一种简单的方法可以使用 OSGi 使外部接口可用，同时隐藏内部接口。至少这是第二个问题的答案。

如果您想在一个子集上运行 javadoc，您也可以随时将项目分解为多个源代码树...