javadoc子集/Java库组织 [英] javadoc subsets / java library organization

问题描述

我从不亲自运行javadoc(无论是在命令行还是 ant的javadoc任务；我将使用ant)-我需要为我编写的库生成一个Javadoc.

I've never run javadoc myself (whether at command-line or ant's javadoc task; I'll be using ant) -- I need to produce a javadoc for a library that I've written.

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

The problem is that my java library is organized into several packages, and there's no way in Java to make classes public within a library but not public to the outside world, so I have a bunch of classes that are public from an implementation standpoint but not a semantic standpoint from the library's point of view.

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

So I need to figure out two things.

1. (短期解决方案)是否可以为打算由我的库的使用者使用的类/接口/方法的特定子集生成javadoc?

1. (short-term solution) Is there a way of producing javadoc for a specific subset of classes/interfaces/methods that are meant to be used by consumers of my library?

我如何重组图书馆以确保公开意味着公开?

How could I reorganize the library to make sure that public means public?

推荐答案

如果您可以按包将 public public 与 internal public 类分开(例如，有一些软件包其中包含您的库用户所需的所有公共类，而没有其他公共类)，则只需在这些软件包上运行Javadoc.

If you can separate the public public from the internal public classes by package (i.e. have some packages which contain all the public classes needed for users of your library, and no other public classes), then simply run Javadoc only on these packages.

Javadoc的工作方式是提供要使用的软件包列表(以及查找这些软件包的源路径)，并仅为这些软件包生成文档.

Javadoc works by giving a list of packages to be used (and additionally a source path to look for those packages), and produces documentation only for these packages.

使用Ant会更加复杂，因为默认情况下，使用<packageset>来使用javadoc任务的最简单方法将占用给定目录中的所有软件包.

With Ant it is a bit more complicated, since the easiest way to use the javadoc task, using a <packageset>, takes by default all packages in the given directory.

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

Here is an example with only one package:

  <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>

您可以查看结果，但这实际上不是一个很好的选择例如，由于这里的主包包含许多非供消费者使用的类.

You can view the result, but it is in fact not a really good example, as the main package here contains lots of classes which are not for use by consumers.

如果您处于JSch之类的情况，即您不能按软件包将 public public 与 internal public 类分开，因为您有同时包含public和public的软件包.私有类型，仍然有一种方法可以做到这一点. Javadoc还支持不提供包名，而提供单个文件名作为参数.当我花了一些时间弄清楚如何使用ant进行操作时，这里是生成的ant目标代码:

If you are in a situation like JSch, i.e. you can't separate the public public from the internal public classes by package since you have packages containing both public and private types, there is still a way to do this. Javadoc also supports giving not package-names, but individual file names as parameters. As I just spent some time to figure out how to do this with ant, here the resulting ant target code:

  <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=...的简单文件集也可以工作(并且也可以使用模式而不是简单的列表).

The source files are listed in simpleclasses.list here, using a resourcelist. I think a simple fileset with includesfile=... would have worked, too (and it also would have allowed patterns instead of a simple list).

我必须搜索相当长时间的要点:如果您提供sourcepath属性而不提供任何packagenames属性或<package>子元素，则ant将自动提供默认的所有包"到提到的文件，结果是不排除任何内容. (我们希望sourcepath在这里允许从未记录的类继承文档.)因此，我们还必须提供excludepackagenames="*"，这样现在只有<sourcefiles>元素定义了要记录的内容.

The important point I had to search quite a while: If you give a sourcepath attribute and do not give any packagenames attribute or <package> subelement, ant will automatically provide an "all packages" default, in addition to the mentioned files, which results on not excluding anything. (We want the sourcepath here to allow inheriting documentation from non-documented classes.) So, we have to also provide excludepackagenames="*", such that now only the <sourcefiles> element defines what would be documented.

结果现在看起来更好了，谢谢您的提问.

这篇关于javadoc子集/Java库组织的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！