javadoc 子集/java 库组织

Question

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

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

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

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

2. 我如何重组图书馆以确保公共(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>元素定义要记录的内容。

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