Question

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

问题是我的java库被组织成几个包，并且在Java中没有办法让类在库中公开但不公开到外部世界，所以我有一堆类{{1}从实现的角度来看，但从图书馆的角度来看，这不是语义立场。

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

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

Answer 1

如果您可以通过包将公共公共与内部公共类分开（即，有一些包含库的用户所需的所有公共类，以及没有其他公共类），只需在这些包上运行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和私人类型，还有一种方法可以做到这一点。 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>

源文件使用resourcelist在simpleclasses.list中列出。我认为一个带有includesfile=...的简单文件集也会起作用（它也会允许模式而不是简单的列表）。

重要的一点是我必须搜索一段时间：如果您提供sourcepath属性并且不提供任何packagenames属性或<package>子元素，则ant会自动提供“全部包“默认，除了提到的文件，结果不排除任何东西。（我们希望这里的sourcepath允许从未记录的类继承文档。）因此，我们还必须提供excludepackagenames="*"，这样现在只有<sourcefiles>元素定义了要记录的内容

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

Answer 2

首先，使用OSGi可以轻松地在隐藏内部结构的同时使外部接口可用。这至少是＃2的答案。

如果你想在一个子集上运行javadoc，你总是可以将项目分解为多个源树...

javadoc子集/ java库组织

2 个答案: