Блог

Я никогда не запускал javadoc сам (будь то в командной строке или в задаче ant javadoc; я буду использовать ant) — мне нужно создать javadoc для библиотеки, которую я написал.

Проблема в том, что моя библиотека Java организована в несколько пакетов, и в Java нет способа сделать классы общедоступными внутри библиотеки, но не общедоступными для внешнего мира, поэтому у меня есть куча классов, которые public являются с точки зрения реализации, но не семантической точки зрения с точки зрения библиотеки.

Итак, мне нужно выяснить две вещи.

1. (краткосрочное решение) Существует ли способ создания javadoc для определенного подмножества классов / интерфейсов / методов, которые предназначены для использования потребителями моей библиотеки?

2. Как я мог бы реорганизовать библиотеку, чтобы убедиться, что 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 amp;<a href="http://www.jcraft.com/jsch/">official homepageamp;</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 amp;<a href="http://epaul.github.com/jsch-documentation/javadoc/">inofficial Javadocamp;</a> created by Paŭlo Ebermann.
        Have a look at the amp;<a href="http://www.jcraft.com/jsch/">official homepageamp;</a>.
      </bottom>
      <link href="http://download.oracle.com/javase/6/docs/api/" />
    </javadoc>
  </target>
  

Исходные файлы перечислены в простых классах.перечислите здесь, используя resourcelist . Я думаю, что простой набор файлов с includesfile=... тоже сработал бы (и это также позволило бы использовать шаблоны вместо простого списка).

Важный момент, который мне пришлось довольно долго искать: если вы задаете sourcepath атрибут и не указываете какой-либо packagenames атрибут или <package> подэлемент, ant автоматически предоставит значение «все пакеты» по умолчанию, в дополнение к упомянутым файлам, что приводит к тому, что ничего не исключается. (Мы хотим, чтобы sourcepath здесь разрешалось наследование документации от недокументированных классов.) Итак, мы должны также предоставить excludepackagenames="*" такой, чтобы теперь только <sourcefiles> элемент определял, что будет документировано.

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

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

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