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

Question

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

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

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

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

2. Как я могу реорганизовать библиотеку, чтобы общедоступность означала общедоступность?

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>

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

---

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

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

Answer 2

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

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