javadoc subsets / java library organization

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.

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. (short-term solution) Is there a way of producing javadoc for a specifi开发者_运维知识库c subset of classes/interfaces/methods that are meant to be used by consumers of my library?

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

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

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.

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>

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

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.

The result looks now much nicer, thanks for the question.

First, there is an easy way to make external interfaces available while hiding internals, using OSGi. This is the answer to #2, at least.

You could always break the project down into multiple source trees, too, if you wanted to run javadoc over a subset...