javadoc 子集/java 库组织

Question

我自己从来没有运行过javadoc(无论是在命令行还是ant's javadoc task；我将使用ant)——我需要为我编写的库生成一个javadoc。

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

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

(短期解决方案)有没有办法为我的图书馆的消费者使用的类/接口(interface)/方法的特定子集生成 javadoc？

我如何重组图书馆以确保公共(public)意味着公共(public)？

Answer 1

如果您可以通过包将公共(public)公共(public)与内部公共(public)类分开(即，有一些包包含库用户所需的所有公共(public)类，并且没有其他公共(public)类)，那么只需在这些包上运行 Javadoc。

Javadoc 通过提供要使用的包列表(以及查找这些包的源路径)来工作，并且只为这些包生成文档。

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

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

  <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 &lt;a href="http://www.jcraft.com/jsch/">official homepage&lt;/a>.
      </bottom>
      <link href="http://download.oracle.com/javase/6/docs/api/" />
    </javadoc>
  </target>

您可以 view the result ，但实际上它并不是一个很好的例子，因为这里的主包包含许多类，它们是 不是 供消费者使用。

如果您处于 JSch 之类的情况，即您无法通过包将公共(public)公共(public)类与内部公共(public)类分开，因为您有包含公共(public)和私有(private)类型的包，仍然有一种方法可以做到这一点。 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 &lt;a href="http://epaul.github.com/jsch-documentation/javadoc/">inofficial Javadoc&lt;/a> created by Paŭlo Ebermann.
        Have a look at the &lt;a href="http://www.jcraft.com/jsch/">official homepage&lt;/a>.
      </bottom>
      <link href="http://download.oracle.com/javase/6/docs/api/" />
    </javadoc>
  </target>

源文件在 simpleclasses.list 中列出在这里，使用 resourcelist .我认为一个简单的文件集 includesfile=...也会起作用(而且它也会允许模式而不是简单的列表)。

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

The result looks now much nicer ，谢谢你的提问。