подмножества javadoc/организация библиотеки java

Если вы можете отделить общедоступные классы от внутренних общедоступных классов по пакетам (т. е. иметь несколько пакетов, содержащих все общедоступные классы, необходимые для пользователей вашей библиотеки, классы), затем просто запустите 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>

Вы можете просмотреть результат, но на самом деле это не очень хороший пример, так как основной пакет здесь содержит множество классов, которые не предназначены для использования потребителями.

Если вы находитесь в ситуации, подобной JSch, то есть вы не можете разделить общедоступные общедоступные классы от внутренних общедоступных классов по пакетам, поскольку у вас есть пакеты, содержащие как общедоступные, так и частные типы, есть еще способ сделать это. 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> определял, что будет задокументировано.

Теперь результат выглядит намного лучше, спасибо за вопрос.

Во-первых, есть простой способ сделать внешние интерфейсы доступными, скрывая внутренние, используя OSGi. Это ответ на № 2, по крайней мере.

Вы также всегда можете разбить проект на несколько исходных деревьев, если хотите запустить javadoc для подмножества...