javadoc 子集/java 库组织答案

【问题标题】：javadoc subsets / java library organizationjavadoc 子集/java 库组织
【发布时间】：2011-04-25 15:08:19
【问题描述】：

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

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

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

（短期解决方案）有没有办法为我的库的消费者使用的特定类/接口/方法子集生成 javadoc？
我如何重组图书馆以确保公开意味着公开？

【问题讨论】：

标签： java javadoc public

【解决方案1】：

如果您可以通过包将 public public 与 internal 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 与 internal 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 &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，感谢您的提问。

【讨论】：

感谢您的帮助！ <resourcelist><file ...> 给我一个关于嵌套资源的错误，但如果我将 <sourcefiles> 与资源集合一起使用，我可以让它正常工作。

【解决方案2】：

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

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

【讨论】：