Содержание


Создание справочной документации API Java ™DITA с использованием DITADoclet и специализации DITA API

Автоматическое создание справочной документации из исходного кода Java с помощью специализации DITA API

Comments

Преследуемые цели

Из этой статьи вы узнаете, как использовать специализацию DITADoclet решения DITA API Java , а также среду разработки Eclipse для создания справочной документации по API Java для удобства ее распространения во многих форматах. DITADoclet генерирует файлы DITA API Java, автоматически создает файлы DITAMAP и MAPLIST (специализация DITA API Java) для справочной документации API Java, извлекает комментарии разработчика из исходного кода Java и переносит информацию в создаваемые файлы DITA API.

Для создания справочной документации API Java из исходного кода Java обычно используется инструмент Javadoc от Sun Microsystems. Он генерирует базовую структуру справочной документации API Java, но эта документация часто получается неполной и ограничена комментариями разработчика. В группах разработчиков происходят изменения, направленные на полное исключение авторов и редакторов из процесса разработки справочной документации API Java. У разработчиков есть время только на то, чтобы управлять файлами исходного кода Java с неполными комментариями. Эта ситуация ставит технических писателей и всех, кто заинтересован в производстве высококачественной документации API, в затруднительное положение.

Решение DITADoclet и DITA API Java предоставляет авторам API инструменты для создания полностью документированных API Java. Полностью документированный API может служить нескольким целям, но главное – предоставить пользователям API возможность полного понимания, поиска и просмотра доступных им функций API. Для полноценного использования функциональных возможностей API пользователям программного обеспечения требуется точный и полностью документированный API.

Чтобы объяснить, как работает DITADoclet, в статье также даются некоторые важные понятия стандарта Javadoc, которые использует решение доклета. Для того чтобы функция автоматического извлечения DITADoclet работала эффективно, исходный код Java нужно документировать в строгом соответствии с руководящими принципами Javadoc. В противном случае при извлечении комментариев с помощью DITADoclet они могут не обработаться должным образом, или результирующая документация API может оказаться неполной.

Эта статья содержит следующие разделы:

  • Предварительные замечания
  • Что такое специализация DITA API Java?
  • Установка DITADoclet
  • Создание документации Javadoc с помощью мастера Eclipse Javadoc Generation (Standard Doclet)
  • Создание справочной документации API Java с помощью:
    • Eclipse Javadoc Generation Wizard (DITADoclet)
    • командной строки
  • «Преимущества и недостатки DITADoclet

Чтобы скачать DITADoclet, обращайтесь к разделу Загрузки.

Чтобы больше узнать о DITA, способах создания и редактирования файлов DITA и о других XML-редакторах, поддерживающих DITA, обращайтесь на веб-сайт http://dita.xml.org. Во избежание ошибок тегирования я настоятельно рекомендую использовать XML-редактор. Имеется множество различных XML-редакторов: Arbortext Editor™, <oXygen/>® XML Editor, XMLBuddy™ (Eclipse-плагин), Altova® XMLSpy®, OpenOffice.org и многие другие. Я рекомендую использовать в качестве системы публикации информации Arbortext Editor.

Аудитория

Этот материал предназначен для авторов API и предполагает знакомство с программным обеспечением Java, структурой справочной документации API Java и генерированием Javadoc, а также желание автора API больше узнать о том, как достичь высокого качества справочной документации API Java.

Ожидается, что авторы API понимают код, написанный разработчиками, и извлекают соответствующую информацию, которую следует опубликовать в документации API. Успех, которого можно достичь, используя DITADoclet для создания документации DITA API Java, зависит от знакомства с исходным кодом Java.

Предварительные замечания

В этой статье объясняется, что нужно для создания справочных файлов DITA API Java непосредственно из исходного кода Java и как преобразовать эти файлы с помощью Eclipse. Чтобы использовать DITADoclet и специализацию DITA API Java, требуется знакомство со следующими понятиями:

  • процессы создания справочной документации API Java и генерирования файлов Javadoc;
  • Eclipse:
    • перспективы и представления IDE и редакторов Java;
    • основные понятия Eclipse, такие как архитектура, плагины и включение в рабочую среду;
    • элементы минимального плагина, такие как проекты, представления Eclipse и редакторы;
    • способы создания, установки и запуска простого плагина с помощью Java IDE Eclipse;
  • Eclipse – базовая интегрированная среда разработки, но существует много связанных с Java плагинов для Eclipse, а также ряд коммерческих IDE, построенных поверх Eclipse:
    • Rational® Software Architect – всеобъемлющая интегрированная среда разработки для визуального проектирования, конструирования, тестирования, профилирования и развертывания приложений;
    • Rational Application Developer для WebSphere Software дополняет Eclipse средствами визуальной разработки;
    • IBM® WebSphere® Studio – мощная и популярная IDE J2EE от IBM;
    • IBM WebSphere Studio Site Developer для Java – IDE Java для Windows и Linux;
    • Sun Java Studio Creator;
    • JBuilder.

Чтобы загрузить эти плагины, обращайтесь к разделу Ресурсы. Я рекомендую запускать DITADoclet либо с помощью инструмента сборки Eclipse, либо непосредственно из командной строки.

Что такое специализация DITA API Java?

Те, кто знаком с DITA, могут пропустить это описание и перейти к следующему разделу Установка DITADoclet.

DITA обеспечивает создание согласованной, полной и правильной технической документации. Специализация DITA API представляет собой пакет типов топиков DITA, производящий файлы документации API Java. DITADoclet генерирует файлы DITA непосредственно из исходного кода Java. Его можно запустить из командной строки или с помощью Eclipse.

Архитектура типизированной информации Darwin (DITA)

DITA – это открытый стандарт OASIS, основанный на XML-архитектуре для разработки, изготовления и доставки технической информации. Хотя файлы DITA можно редактировать в любом текстовом редакторе, XML-редакторы позволяют легко вставлять и изменять теги в соответствии с DTD и схемами DITA. Во избежание ошибок тегирования я рекомендую использовать XML-редактор. В число доступных XML-редакторов входят Arbortext Editor, oXygen, XML Buddy (Eclipse-плагин), Altova XML Spy и др.

Чтобы больше узнать о DITA, способах создания и редактирования файлов DITA и о других XML-редакторах, поддерживающих DITA, обращайтесь на веб-сайт организации (см. раздел Ресурсы).

Открытая платформа DITA Open Platform – это бесплатное программное обеспечение, которое можно распространять и модифицировать на условиях лицензии GNU General Public License, опубликованной Фондом свободного программного обеспечения. DITA Open Platform распространяется в надежде на то, что она окажется полезной, но без каких-либо гарантий. Подробнее см. в разделе Ресурсы.

Специализация DITA API

Документация по специализации DITA API описывает XML-архитектуру DITA посредством элементов DTD в общем виде (для всех языков программирования) и для языка программирования Java. Специализации DITA API включает в себя типы топиков и элементы для документирования справочной информации в общем виде и для API Java. Специализация DITA API для каждого языка состоит из модулей. Модуль — это тип топиков, предназначенный для решения конкретной задачи, такой как описание пакета или класса API. Каждый модуль включает в себя соответствующие XML-элементы для описания конкретной части языка программирования.

Эта статья учит применять DITADoclet для создания справочных файлов DITA API Java и использовать решение DITA API Java для документирования справочной информации.

Специализацию DITA Generic API можно использовать для разработки и создания справочной документации API для Java, Visual Basic и других языков программирования.

Установка DITADoclet

Чтобы запустить DITADoclet, нужно установить Java Development Kit (JDK) и Eclipse.

Установка JDK

  • Запуск этого инструмента может закончиться неудачей, если двоичные файлы Java не содержатся по системному пути или если не определена переменная среды JAVA_HOME. Для запуска DITADoclet нужен JDK.
  • Рекомендуется Java 5 JDK. Как правило, путь установки Java имеет вид C:\Program Files\Java\jdk1.5.0_06\. Чтобы определить, какая версия Java установлена на вашей системе, наберите в командной строке: Java -version
  • Если у вас не последняя версия Java, скачайте JDK, J2RE или JRE с сайта загрузок Sun (см. раздел Ресурсы).

Установка Eclipse Classic

  • Загрузите Eclipse Classic для Windows, IBM Rational Developer или Rational Software Architect Standard Edition и распакуйте zip-файл в каталог по своему выбору (например, C:\eclipse\ в системе Windows). См. раздел Ресурсы.
  • Главное – чтобы на платформе Windows путь установки Eclipse не содержал пробелов. Подробнее об установке различных инструментов см. в официальной документации Eclipse. Чтобы проверить, установлен ли у вас инструмент Javadoc, откройте командную строку и введите Javadoc. Если вы получили сообщение об ошибке, значит Javadoc (jdk1.5.0_xx) у вас нет и вам нужно скачать jdk1.5.0_xx с веб-сайта Sun и добавить в свой путь Windows следующий каталог: C:\Program Files\Java\jdk1.5.0_xx.

Установка DITADoclet

  • Загрузите zip-файл DITADoclet Tool и распакуйте его в каталог по своему выбору (например, C:\DITA\ в системе Windows). Будет создан каталог \DITA, содержащий файлы DITADoclet.exe, ReadeMe.txt и подкаталог \demo.
    • В подкаталоге \demo содержится каталог ресурсов, опций и пакетов \src.
    • В каталоге ресурсов \src содержатся файлы исходного кода Java, которые мы будем использовать в качестве примеров. Эти файлы (DITA-OT1.4_src.zip) можно загрузить непосредственно с веб-сайта SourceForge.

Установка плагина org.dita.dost

  1. Найдите каталог workspace, используемый в вашей версии Eclipse. Обычно он расположен внутри каталога \workspace, в подкаталоге которого установлен Eclipse. Если для запуска Eclipse используется ярлык или сценарий, то он будет находиться в текущем рабочем каталоге этого ярлыка или сценария, расположенном в подкаталоге \workspace (например, C:\eclipse\workspace).
  2. Загрузите zip-файл org.dita.dost (см. раздел Загрузки) и распакуйте его в рабочий каталог Eclipse. Будет создан проект Java с именем org.dita.dost.
  3. Импортируйте проект Java org.dita.dost в рабочую область Eclipse.

Дополнительные шаги по установке

Следующие шаги необязательны, и я не буду здесь объяснять их. Для завершения и проверки файлов DITA API необходимо преобразовать файлы .dita в файлы .xhtml. Для преобразования файлов DITA API Java или получения выходных данных из файлов DITA API можно использовать DITA Open Toolkit. Для работы преобразователя нужно установить плагины apiref и javaapiref.

  1. Дополнительно: скачайте и установите DITA Open Toolkit.
  2. Дополнительно: скачайте и установите специализацию DITA API Java (apiref-0.8 и avaapiref-0.8).

Создание документации Javadoc с помощью Standard Doclet (мастера Eclipse Javadoc Generation)

Для понимания основополагающей роли и структуры DITADoclet полезно вкратце рассмотреть инструмент Javadoc. Подробное описание параметров инструмента Javadoc приводится в документации JDK. Те, кто знаком с инструментом Javadoc, могут сразу использовать DITADoclet. Инструмент Javadoc (или DITADoclet) анализирует файлы исходного текста, извлекает комментарии Javadoc и строит внутреннюю коллекцию данных документации.

Следующие шаги показывают, как сгенерировать Javadoc в среде разработки Eclipse, используя Standard Javadoc Doclet.

  1. Для иллюстрации процесса мы будем использовать один из плагинов Eclipse, org.dita.dost.
  2. В Eclipse, на левой панели в представлении Package Explorer, выберите исходный код Java, для которого нужно сгенерировать Javadoc (в данном примере используется один из плагинов Eclipse, org.dita.dost). Щелкните правой кнопкой мыши на org.dita.dost и выберите из раскрывающегося списка Export. Откроется окно Export.
  3. Выберите Javadoc и нажмите кнопку Next. Откроется окно Generate Javadoc.
  4. В окне конфигурации Javadoc Command: выберите Javadoc.exe. Как правило, файл Javadoc.exe имеет путь C:\Program Files\Java\jdk1.5.0_06\bin\Javadoc.exe (см. рисунок 1).
    Рисунок 1. Выбор пути javadoc.exe
    Выбор пути javadoc.exe
    Выбор пути javadoc.exe
  5. В окне Generate Javadoc выберите пакеты, которые нужно экспортировать в файлы Javadoc. Этот список инициализируется при выборе рабочего пространства Eclipse. Можно выбрать только один проект, так как во время работы инструмента Javadoc можно использовать только один classpath проекта.
  6. Чтобы отфильтровать компоненты пакета, выберите видимость (обычно выбирают Public.)
    • Возможные варианты: -package, -private, -protected, или -public, как показано на рисунке 2.
      Рисунок 2. Выбор видимости компонентов
      Выбор видимости компонентов
      Выбор видимости компонентов
    • Таблица 1 иллюстрирует компоненты, которые можно выбрать, в зависимости от желаемой видимости. -public выбирает наименьшее, а -private – наибольшее количество компонентов.
Таблица 1. Видимость компонентов
ВариантДокументируемые классы
-publicpublic...
-protectedpublicprotected..
-packagepublicprotected(package).
-privatepublicprotected(package)private
  1. Выберите Use Standard Doclet, чтобы запустить команду Javadoc со стандартным доклетом (по умолчанию).
    • Место назначения: выберите место, куда стандартный доклет будет записывать создаваемую документацию. Место назначения – это аргумент, характеризующий стандартный доклет, поэтому при использовании специального доклета он не включается. Местом назначения для стандартного доклета может быть, например, подкаталог рабочего пространства\workspace\doc.dita.dost\output.
  2. Нажмите кнопку Next, чтобы задать дополнительные параметры создания Javadoc.
  3. Снимите флажок Overview как показано на рисунке 3. Если этот параметр выбран, он указывает на то, что Javadoc должен извлекать из указанного исходного файла текст для обзорной документации и размещать его на странице Overview (index.html).
    Рисунок 3. Расположение страницы Overview
    Параметр overview
    Параметр overview
  4. Нажмите кнопку Next, чтобы задать дополнительные параметры создания Javadoc.
  5. Укажите заголовок, который помещается в верхней части файла index.html. Если не выбрать и не указать заголовок документа, Javadoc не добавит его на страницу Overview.
    Рисунок 4. Указание заголовка документа
    Название документа
    Название документа

Дополнительные параметры Javadoc

Может потребоваться добавить дополнительные параметры Javadoc для обработки инструментом Javadoc. Они принимают форму VM options. Это параметры системы, используемые для управления обработкой Javadoc. Например, установка -Xmx512m приведет к выделению 512 МБ памяти для кучи.

  1. Чтобы ускорить процесс обработки и выключить все информационные сообщения Javadoc, я предлагаю использовать параметр -quiet, что поможет создавать комментарии Javadoc. (Совет. Еще один параметр, который можно использовать, – это -verbose. Параметр -verbose заставляет компилятор и Javadoc выводить сообщения о том, какие исходные файлы компилируются и какие файлы классов документируются.)
    Рисунок 5. Указание параметров VM и Javadoc
    Параметры виртуальной машины и Javadoc
    Параметры виртуальной машины и Javadoc
  2. Доклет генерирует выходные HTML-файлы документации плагина в подкаталог рабочей области \workspace\org.dita.dost\output\, который служит каталогом документации плагина.
  3. Нажмите кнопку Finish, чтобы создать документацию Javadoc. Наблюдайте за ходом создания JavaDoc с помощью представления консоли.

Javadoc получает всю информацию и текст из исходных файлов Java, за двумя исключениями: текстового файла обзора и текстового файла для каждого пакета. Оба эти исключения опциональны. Файлы, созданные Javadoc, это соответственно index.html и package-summary.html. При использовании стандартного Javadoc сгенерированные файлы обзора и пакетов будут HTML-файлами без всякой информации. Документация пакета предоставляет разработчикам необходимые сведения об использовании пакетов. Сведения о пакете полезны для понимания того, как все работает вместе, и могут включать код, прототип, структурные схемы, модели, стандарты кодирования и т.п. Если выбрано открытие индексного файла в браузере, то после создания Javadoc страница Javadoc index.html будет открыта в веб-браузере по умолчанию.

Теперь, когда мы показали, как Javadoc генерирует справочные файлы API Java, рассмотрим аналогичный процесс созданияфайлов DITA справочной документации API Java инструментом DITADoclet. В следующем разделе вы увидите, как создать справочную документацию API Java с Eclipse Javadoc Generation Wizard (DITADoclet).

Создание справочной документации API Java с помощью DITADoclet (Eclipse Javadoc Generation Wizard)

DITADoclet анализирует исходные файлы, извлекает комментарии Javadoc и составляет файлы DITA непосредственно из файлов исходного кода API Java. Цель этого проекта заключается в том, чтобы облегчить техническим писателям-авторам API использование своего знакомства с мастером Eclipse Javadoc Generation и чтобы им нужно было дополнительно усвоить лишь минимальный набор особенностей документации DITA:

  • DITADoclet генерирует документацию с той же общей структурой, что и у документации, созданной посредством стандартного Doclet;
  • DITADoclet поддерживает все возможности, предоставляемые стандартным Doclet, но учитывает только следующие параметры: -sourcepath, -d, -doctitle, -overview, и -public;
  • DITADoclet также поддерживает несколько дополнительных параметров, которые можно использовать: -contributor, -provider, -debug, и -nocomment.
  • Стандартный доклет обрабатывает теги специальных блоков с помощью теглетов, а DITADoclet – нет.

В следующих пунктах показано, как использовать специальный доклет DITADoclet в сочетании с Javadoc в среде разработки Eclipse.

  1. На левой панели Eclipse выберите org.dita.dost, плагин исходного кода, для которого нужно сгенерировать Javadoc.
  2. Щелкните правой кнопкой мыши на выбранном плагине и выберите из раскрывающегося списка Export. Откроется окно Export.
  3. Выберите Javadoc и нажмите кнопку Next. Откроется окно Generate Javadoc.
    Рисунок 6. Мастер формирования Javadoc (Standard Doclet) с открытым окном Generate Javadoc
    Мастер формирования Javadoc (Standard Doclet) с открытым окном Generate Javadoc
    Мастер формирования Javadoc (Standard Doclet) с открытым окном Generate Javadoc
  4. В поле Javadoc command укажите путь к файлу DITADoclet.exe. При установке DITADoclet он вероятно, установился как C:\DITA\DITADoclet.exe.
  5. В окне Generate Javadoc выберите пакеты, которые нужно экспортировать в файл Javadoc. Этот список инициализируется рабочей областью Eclipse. Можно выбрать только один проект, так как во время работы инструмента Javadoc можно использовать только один classpath проекта. Выделите пример проекта org.dida.dost.
  6. Так как эта версия специализации DITA API Java поддерживает только открытые элементы Java, выберите члены со значением видимости Public.
  7. Выберите Use Standard Doclet, чтобы запустить команду Javadoc со стандартным доклетом (по умолчанию).
  8. Укажите место, куда стандартный доклет будет записывать создаваемую документацию. (Место назначения – это аргумент, характеризующий стандартный доклет, поэтому при использовании специального доклета он не включается.) Местом, куда будет писать стандартный доклет, может быть, например, подкаталог рабочей области ..\workspace\doc.DITA.dost\topics.
  9. Нажмите кнопку Next, чтобы перейти к основным параметрам.
    Рисунок 7. Мастер формирования Javadoc (стандартный доклет) - выбор основных параметров Javadoc
    Мастер формирования Javadoc (стандартный доклет) - выбор основных параметров Javadoc
    Мастер формирования Javadoc (стандартный доклет) - выбор основных параметров Javadoc
  10. В поле Document title укажите заголовок, размещаемый в верхней части файла краткого обзора. Если опустить заголовок документа, DITADoclet добавит заголовок по умолчанию: Building DITA output.
  11. Снимите флажки основных параметров Javadoc, как показано на рисунке 7. Ниже перечислены доступные параметры и способ их обработки инструментом DITADoclet.
    • Generate use page (создать страницу use): DITADoclet не создает страницу use.
    • Generate hierarchy tree (Создать дерево иерархии): DITADoclet автоматически создает страницу дерева иерархии независимо от того, отмечен ли этот параметр.
    • Generate navigation bar (Создать панель навигации): DITADoclet автоматически создает панель навигации для каждой страницы независимо от того, отмечен ли этот параметр.
    • Generate index (Создать индекс): DITADoclet автоматически создает страницу индекса независимо от того, отмечен ли этот параметр.
    • Separate index per letter (Отдельный индекс для каждой буквы): DITADoclet не будет создавать отдельный индекс для страниц на каждую букву.
  12. Снимите флажки параметров Document these tags, как показано на рисунке 7.
    • @author: DITADoclet автоматически добавит автора на страницу meta независимо от того, отмечен ли этот параметр.
    • @version: DITADoclet автоматически добавит версию на страницу .dita независимо от того, отмечен ли этот параметр.
    • @deprecated: DITADoclet автоматически добавит устаревшую информацию на страницу .dita независимо от того, отмечен ли этот параметр.
    • @deprecated list: DITADoclet не будет создавать страницу устаревшей информации.
  13. Имейте в виду, что DITADoclet принимает во внимание только значение поля Destination и параметры Document title. В этом примере значение Destination: ..\workspace\doc.DITA.dost\topics. Значение параметра Document title: DITA-OT. Если значение поля Destination не задано, DITADoclet создаст все файлы .dita в папке с исходным кодом (\src). Если опустить параметр Document title, DITADoclet добавит заголовок по умолчанию: Building DITA output.
  14. Вы еще не создали файл overview.html, поэтому не устанавливайте флажок Overview. (При запуске инструмента во второй раз можно будет выбрать уже созданный файл overview.html из папки \workspace\src.)
    Рисунок 8. Не указывайте путь к странице обзора
    Путь к странице обзора
    Путь к странице обзора
  15. Нажмите кнопку Next, чтобы выбрать дополнительные параметры Javadoc (пути, содержащие имена с пробелами, должны быть заключены в кавычки). Можно выбрать следующие параметры:
    Рисунок 9. Дополнительные параметры javadoc
    Дополнительные параметры javadoc
    Дополнительные параметры javadoc
    • -contributor включает в создаваемую DITA авторский текст;
    • -provider указывает имя поставщика плагина;
    • -debug выводит на консоль Javadoc предупредительные сообщения
  16. Параметры -contributor и –provider добавляют во все генерируемые файлы DITA раздел пролога, содержащий имя автора, имя соавтора, имя поставщика, дату создания и т.п. См. следующий пример.
    • Имя автора <author type="creator">Lian, Li</author> берется из тегов javadoc @author исходного кода.
    • Имя соавтора <author type="contributor">MarianaAlupului</author> берется из параметра Javadoc -contributor, как показано на рисунке 9.
    Листинг 1. Вывод <пролога>
    <prolog>
       <author type="creator">Lian, Li</author>
       <author type="contributor">Mariana Alupului</author>
       <source href="org/dita/dost/xxx.Java">org/dita/dost/test/xxx.Java</source>
       <publisher>IBM</publisher>
       <copyright type="primary">
         <copyryear year="2008"/>
         <copyrholder>IBM</copyrholder>
       </copyright>
       <critdates>
       <created date="Wed, 17-Dec-2008 12:20:16 EST"/>
       <revised modified="Fri, 19-Dec-2008 15:49:48 EST" status="new"/>
       </critdates>
    </prolog>
  17. Нажмите кнопку Finish, чтобы создать документацию DITA API.

Дополнительные замечания

DITADoclet выводит на консоль Eclipse все предупреждения, которые могут помочь обнаружить ошибки или упущения в документации (см. рисунок 10). По умолчанию эти предупреждения не выводятся. Чтобы заказать их, используйте параметр -debug.

Рисунок 10. Консоль Javadoc с примером сообщений и предупреждений
Консоль Javadoc с примером сообщений и предупреждений
Консоль Javadoc с примером сообщений и предупреждений

Файлы журнала событий могут автоматически сохраняться при достижении определенного размера. Для этого в консоли нажмите клавиши Ctrl-Break. Это особенно полезно при выполнении сценариев с параметром -debug, так как можно увидеть, что происходит при генерировании документации в системе Eclipse. Файлы журнала также можно направить разработчикам, что поможет им выявить исходные файлы, в которых отсутствует информация, предупреждения и т.п.

Файлы навигации DITADoclet

DITADoclet записывает в папку org.dita.dost\topics\ выходные файлы DITA (XML) для плагина и несколько других файлов навигации. DITADoclet создает следующие файлы навигации:

  • org.dita.dost.ditamap
  • org.dita.dost.doc.reltable.ditamap
  • org.dita.dost.doc.ditaval
  • org.dita.dost.doc.maplist

Файл org.DITA.Dost.ditamap

Файл ditamap содержит имя страницы Java API Reference и все элементы, необходимые для описания пакета или набора пакетов и его компонентов.

Рисунок 11. Выходные данные DITA - файл org.dita.dost.ditamap
Выходные данные DITA - файл org.dita.dost.ditamap
Выходные данные DITA - файл org.dita.dost.ditamap

Файл org.DITA.Dost.doc.reltable.ditamap

Файл reltable определяет таблицы взаимосвязей для управления внутренними классами и интерфейсами. При отсутствии внутренних классов или интерфейсов DITADoclet не создает файла reltable.

Файл org.DITA.Dost.doc.ditaval

Элементы файла ditaval DITA можно фильтровать по атрибутам: аудитория, платформа, продукт и др. Значения одного или нескольких из этих атрибутов задается в элементах исходного кода DITA. С помощью этих свойств можно включать или выключать текст; то есть скрывать или отображать его в зависимости от объявленных свойств. Если значение атрибута не используется, можно совсем удалить этот атрибут из файла ditaval. Если значения используются, но вы пока не хотите отмечать их, измените действие в файле ditaval с flag на include (см. рисунок 12).

Рисунок 12. Выходные данные DITA - вкладка Properties в файле org.dita.dost.doc.ditaval
Выходные данные DITA - вкладка Properties в файле org.dita.dost.doc.ditaval
Выходные данные DITA - вкладка Properties в файле org.dita.dost.doc.ditaval

Файл org.dita.dost.doc.maplist

Файл maplist позволяет включать в состав документации ditamap и файл reltable.ditamap. Он работает как мастер-файл и вызывает список таблиц классов, которые в свою очередь вызывают топики DITA.

Рисунок 13. Выходные данные DITA - файл org.dita.dost.doc.maplist
Выходные данные DITA - файл org.dita.dost.doc.maplist
Выходные данные DITA - файл org.dita.dost.doc.maplist

Файлы иерархии

DITADoclet генерирует три файла с описанием иерархии классов, списком классов и интерфейсов и индексом классов, интерфейсов, конструкторов, методов и полей.

  • tree.dita
  • allnames.dita
  • allclasses.dita

Страница Java API Reference содержит ссылки на каждое представление.

Рисунок 14. Ссылки на страницы индексов и иерархии на странице Java API Reference
Ссылки на страницы индексов и иерархии на странице Java API Reference
Ссылки на страницы индексов и иерархии на странице Java API Reference

Рассмотрим эти три файла и их содержимое.

Файл tree.dita

Страница Class Hierarchy (рисунок 15) в файле tree.dita содержит список классов и список интерфейсов (всех пакетов). Классы организованы в древовидную структуру, начиная с Java.lang.Object.

Рисунок 15. Иерархия классов в файле tree.dita
Иерархия классов в файле tree.dita
Иерархия классов в файле tree.dita

Файл allnames.dita

Индекс в файле allnames.dita (рисунок 16) содержит алфавитный список всех классов, интерфейсов, конструкторов, методов и полей.

Рисунок 16. Индекс в файле allnames.dita
Индекс в файле allnames.dita
Индекс в файле allnames.dita

Файл allclasses.DITA

Индекс классов и интерфейсов в файле allclasses.dita (рисунок 17) содержит алфавитный список всех классов и интерфейсов.

Рисунок 17. Индекс классов и интерфейсов в файле allclasses.dita
Индекс классов и интерфейсов в файле allclasses.dita
Индекс классов и интерфейсов в файле allclasses.dita

Файлы tree.dita, allnames.dita и allclasses.dita редактировать не нужно. Их редактируют только при наличии ошибок или предупреждений в процессе выполнения преобразователя.

Вспомогательные файлы выходных данных DITA

Файл javastyle.fos представляет собой вспомогательный файл, созданный DITADoclet, который можно использовать с редактором Epic Editor. Этот файл обеспечивает автора визуальным представлением информации, отсутствующей в исходном коде Java, позволяя ему ввести недостающую информацию непосредственно в файлы DITA API Java или в исходный код Java.

При использовании Epic для редактирования файлов, созданных DITA, можно видеть сгенерированный DITADoclet (файл fos) текст, выделенный зеленым цветом, непосредственно в исходном коде Java. Он подчеркивает зеленым недостающие комментарии и предлагает возможную альтернативу для документации. На рисунке 18 показан файл DITA, сгенерированный в DITADoclet и открытый в Epic Editor.

Рисунок 18. Пример файла fos, сгенерированного DITADoclet
Пример файла fos, сгенерированного DITADoclet
Пример файла fos, сгенерированного DITADoclet

При первом запуске DITADoclet этот инструмент создает файл overview.html (листинг 2) и сохраняет его в подкаталоге рабочей области /workspace/org.dita.dost/src. Он также создает файл overview-summary.dita (рисунок 19) и сохраняет его в подкаталоге /workspace/org.dita.dost/topics.

Листинг 2. Файл overview.html
<html>
 <head>
  <title>Building DITA output</title>
<heading  refname="" type="major" back-to-top="no">Headings</heading>
 </head>
 <body>
  Overview short description added in source code src\overview.html template.
  <h2>Overview Specification</h2>
  Overview specification added in source code src\overview.html template.
 </body>
</html>
Рисунок 19. Обзор в файле summary.dita с замечанием
Обзор в файле summary.dita с замечанием
Обзор в файле summary.dita с замечанием

При запуске DITADoclet во второй раз обзор (overview.html) уже будет создан. Теперь можно указать, что DITADoclet следует извлечь текст для этой страницы из файла overview.html. DITADoclet скопирует всю информацию (комментарии разработчика) в файл overview-summary.dita.

При следующем запуске DITADoclet выходной файл будет выглядеть как на рисунке 20.

Рисунок 20. Файл overview-summary.dita без замечания
Обзор в файле summary.dita без замечания
Обзор в файле summary.dita без замечания

Можно изменить файл overview.html или отредактировать текст непосредственно в файле overview-summary.dita. При документировании файла во избежание переопределения этой информации при повторном запуске DITADoclet щелкните правой кнопкой мыши на файле overview-summary.dita. Выберите Properties и установите значение Read-only параметра Attributes.

При первом запуске инструмента DITADoclet он создает файлы package.html и package-summary.dita. Если в исходном коде Java файл package.html отсутствует, то он будет создан. На рисунке 21 приведен пример созданного шаблона файла package-summary.dita. (Во избежание перезаписи информации файла package-summary.dita инструментом DITADoclet щелкните на файле package-summary.dita правой кнопкой мыши. Выберите Properties и установите значение Read-only параметра Attributes. Содержимое файла будет заблокировано).

Рисунок 21. Файл package-summary.dita после первого запуска инструмента DITADoclet
package-summary.dita после первого запуска инструмента DITADoclet
package-summary.dita после первого запуска инструмента DITADoclet

При запуске DITADoclet во второй раз файл package.html уже будет присутствовать в исходном коде Java, и инструмент возьмет всю информацию из этого файла и перенесет ее в файл package-summary.dita. Теперь можно заполнить сведения о пакете в этих файлах. Пример приведен на рисунке 22.

Рисунок 22. Файл package-summary.dita после второго запуска DITADoclet
Файл package-summary.dita после второго запуска DITADoclet
Файл package-summary.dita после второго запуска DITADoclet

Теперь можно выбрать шаблон пакета (файл package.html, сгенерированный при первом запуске инструмента), и DITADoclet автоматически извлечет комментарии разработчика по этой странице и скопирует всю информацию в файл package-summary.dita.

Пример документированного пакета, как он отображается в браузере, приведен на рисунке 23.

Рисунок 23. Документ, как он отображается в браузере

[Short description]
The main package org.dita.dost.log contains the class DITAOTBuildLogger which is responsible to log messages both on the screen and into the log file.
Detailed description:
The messages on the screen present user with the status information, warning, error, and fatal error messages. The messages in the log file present user with more detailed information about the transformation process. By analyzing these messages, user can know what caused the problem and how to solve it.
The logging method is based on Ant's Logger & Listener interface. By default, this logging method is disabled, and all the messages occur on the screen just like previous releases.
Enhanced Ant command:
To start this new logging method, you need to follow the usage below:
  • At an Ant command prompt, specify the logger by appending -logger org.dita.dost.log.DITAOTBuildLogger in the command parameters, for example:
    ant sample.web -logger org.dita.dost.log.DITAOTBuildLogger
  • At a Java command prompt, the logger is specified internally, so you do not need to specify it again.
Important change and future updates:
DITA-OT 1.2 offers new error handling and logging system. If you invoke your transformation with the Java command line where new error handling and logging system is mandatory, you need to set the CLASSPATH Environment Variable for dost.jar. If you invoke your transformation with an ant script, you need to do one more step after the above setting. That is, add a parameter in your command to invoke an ant script. For example, use:
ant
-f ant\sample_xhtml.xml -logger org.dita.dost.log.DITAOTBuildLogger

instead of:
ant -f ant\sample_xhtml.xml

to start a transformation defined in ant script file ant\sample_xhtml.xml.

DITADoclet записывает все выходные файлы в корневой выходной каталог, указанный параметром -d команды, и в подкаталоги этого корневого выходного каталога. Выходной корневой каталог и все его подкаталоги DITADoclet создает автоматически. На рисунке 24 показана структура каталогов и имена файлов по умолчанию, созданные DITADoclet, на примере структуры каталогов, созданной для примера пакета org.dita.dost. Слева показан исходный код Java и составляющие его файлы. Справа представлены файлы DITA, созданные из этой папки с исходным кодом Java.

Рисунок 24. Структура каталогов и имена файлов по умолчанию
Структура каталогов и имена файлов по умолчанию
Структура каталогов и имена файлов по умолчанию

При первом запуске инструмента DITADoclet он создает все файлы DITA. После этого он создаст копии созданных файлов DITA с именами #0.xxx.dita, #1.xxx.dita и т.д. до #64.

Сохранение разных версий этих файлов может помочь в процессе отладки и проверки документации после внесения изменений в комментарии Javadoc в исходном коде Java.

Создание справочной документации API Java с помощью DITADoclet и командной строки

Важно знать, какие параметры считывает и использует Javadoc и какие параметры считывает и использует DITADoclet. Команда Javadoc -help показывает, что инструмент Javadoc имеет два набора параметров командной строки. Один набор – универсальный и будет работать с любым доклетом. Второй набор параметров относится только к стандартному доклету. Параметры из этого второго набора недоступны при использовании специализированных доклетов. Эти специализированные доклеты могут определить свои собственные параметры командной строки. В этой документации содержится только подробное описание всех параметров, предусмотренных для DITADoclet. Подробное описание параметров инструмента Javadoc приводится в документации JDK.

DITADoclet версии 1.1.3 (см. ссылку в разделе ресурсы) в качестве альтернативы предоставляет интерфейс командной строки, чтобы этот инструментарий могли легко применять пользователи, плохо знающие Eclipse.

Запуск Javadoc для примера org.dita.dost

  1. Посмотрите, установлен ли Javadoc в вашем пути. Как правило, путь Javadoc выглядит так: C:\Program Files\Java\jdk1.5.0_06\bin.
  2. С помощью параметра @options разместите параметры в отдельном файле (см. документацию, прилагаемую к JDK.)
  3. С помощью параметра @packages разместите в отдельном файле полные имена пакетов.
  4. Выполните следующую команду из каталога DITA C:\DITA\>: Javadoc @options @packages
Рисунок 25. Параметры и пакеты с использованием примера
JavadocDITADoclet
C:\\DITA\>Javadoc @options @packages
C:\\DITA\>DITADoclet.exe @options @packages
Параметры
-sourcepath demo/src
-d demo/output/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-use
-tree
-navbar
-index
-noauthor
-version
-deprecated
-public
Параметры
-sourcepath demo/src
-d demo/dita/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-provider IBM -contributor "Mariana Alupului"
-public
Пакеты
org.dita.dost.index
org.dita.dost.invoker
org.dita.dost.log
org.dita.dost.module
org.dita.dost.pipeline
org.dita.dost.platform
org.dita.dost.reader
org.dita.dost.util
org.dita.dost.writer
org.dita.dost.exception
Пакеты
org.dita.dost.index
org.dita.dost.invoker
org.dita.dost.log
org.dita.dost.module
org.dita.dost.pipeline
org.dita.dost.platform
org.dita.dost.reader
org.dita.dost.util
org.dita.dost.writer
org.dita.dost.exception

Запуск DITADoclet для примера org.dita.dost

Запуск DITADoclet из командной строки выполняется так же, как и запуск Javadoc:

  1. Чтобы добавить DITADoclet.exe в свой путь, используйте параметр @packages для размещения полных имен пакетов в отдельном файле и параметр @options, чтобы поместить параметры в файл, который можно выполнить из каталога C:\DITA\ посредством следующей команды: DITADoclet @options @packages
  2. Если вы решили набрать всю команду в командной строке, то она должна выглядеть примерно так:

    DITADoclet.exe -sourcepath demo/src -d demo/output/org.dita.dost.doc -overview demo/src/overview-summary.html -doctitle 'Building DITA output' -provider IBM -contributor "Mariana Alupului" org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception

Использование DITADoclet для своего проекта

  • Файлы @options и @packages можно изменить, открыв их в редакторе WordPad.
  • Выполните команду: DITADoclet.exe @options @packages.

Запуск преобразователя DITA-OT для создания XHTML-файлов из DITA

С помощью доклета DITADoclet, представленного в этой статье, можно создать справочную документацию API Java на основе файлов DITA и небольшого числа дополнительных элементов документации. DITADoclet позволяет легко создать документацию на платформе Eclipse, которая затем будет использоваться для создания выходных форматов XML и XHTML для существующих систем справки Eclipse. Со временем можно ожидать появления других выходных форматов.

Преобразователь DITA-OT может генерировать формат HTMLHelp (CHM). На рисунках 26 и 27 приведены примеры CHM-файлов в окне преобразователя DITA-OT, первый с замечаниями, а второй – без них.

Рисунок 26. CHM с замечаниями
CHM с замечаниями
CHM с замечаниями
Рисунок 27. CHM без замечаний
CHM без замечаний
CHM без замечаний

Составитель API должен снять все замечания (см. рисунок 26). Полный и документально оформленный комплект справочной документации API Java не должен содержать никаких замечаний, выделенных зеленым цветом (см. рисунок 27).

Авторы API могут использовать решение для проверки DITADoclet, чтобы выявить всю недостающую информацию из исходного кода Java, и также проверить свою работу по полным и полностью оформленным справочным файлам, прежде чем выпустить исходный код интернет-справки.

Запустив преобразователь DITA-OT, можно из файлов DITA API Java в среде Eclipse создать XHTML-файлы. Таким способом создан пример, приведенный на рисунке 28.

Рисунок 28. Интернет-справка Eclipse
Интернет-справка Eclipse
Интернет-справка Eclipse

Преимущества DITADoclet

Использование DITADoclet для создания документации DITA API Java дает следующие преимущества:

Поиск
Обеспечивается эффективный способ поиска методов и классов или интерфейсов. Система Javadoc не содержит такого механизма поиска в оглавлении (TOC).
Навигация
Обеспечивает навигацию с помощью TOC, который генерируется автоматически непосредственно из исходного кода Java.
Индекс
Поиск по ключевым словам дополнен индексами. Индексы создаются автором API и, следовательно, могут дать ценную дополнительную информацию.
В индексе перечислены все пакеты, классы, интерфейсы, методы и поля, помещенные в их контекст (например, для метода или поля приводится содержащий класс) и даны ссылки на документ с описанием элемента.
Ссылки
DITA указывает недостающие ссылки, которые трудно найти без использования DITA. В этом демонстрационном проекте (org.dita.dost) имеется 108 тем с 3567 локальными ссылками, которые DITA автоматически проверяет.

Недостатки DITADoclet

Этот инструмент можно использовать для создания файлов DITA API Java только из исходных файлов Java версии 1.4. Следующая версия специализации DITA API и DITADoclet будет поддерживать Java версий 1.5 и 1.6 (в том числе аннотации, перечни, обобщения и т.д.)


Ресурсы для скачивания


Похожие темы

  • Оригинал статьи: Generate DITA Java API reference documentation using DITADoclet and DITA API specialization.
  • Прочтите следующие статьи, посвященные DITA, на developerWorks:
    • Migrating HTML to DITA, Part 1: Simple steps to move from HTML to DITA (Robert Anderson, Don Day, Erik Hennum; developerWorks, январь 2005 г.): о том, как быстро приступить к работе с DITA с использованием уже имеющихся HTML-топиков. Информация переносится с помощью XSLT-преобразования, и даются рекомендации по обеспечению качества результатов.
    • Migrating HTML to DITA, Part 2: Extend the migration for more robust results (Robert Anderson, developerWorks, февраль 2005 г.): подробная информация о миграции и о том, как ее выполнить с идеальными результатами.
    • Introduction to DITA (Don Day, Michael Priestley, David Schell; октябрь 2003 г.): введение в DITA: что это такое и как это применять к технической документации.
    • Specializing topic types in DITA (Michael Priestley, октябрь 2003 г.): о создании новых типов документов на основе топиков для упрощения сборки в расчете на различные условия доставки.
    • Specializing domains in DITA (Erik Hennum, обновление от сентября 2005 г.): о возможностях по дополнению и многократному использованию типов информации для расширения своей базы DTD.
  • Eclipse Platform: актуальная информация об Eclipse, новости, плагины и комментарии сообщества. Читайте дополнительные статьи об Eclipse:
    • Documenting your project using the Eclipse help system (Arthur Barr, developerWorks, январь 2004 г.): как составить простую в применении справочную документацию с возможностью поиска.
    • The Mastering Eclipse V3.4 series (Prashant Deva, developerWorks, октябрь-ноябрь 2008 г., январь 2009 г.): серия из трех статей, посвященная рабочей области IDE Eclipse, JDT и текстовому редактору JDT. К концу серии вы станете опытным пользователем.
  • DITA Open Toolkit: о реализации спецификации DTD и схем DITA Технического комитета OASIS DITA. Инструментарий превращает контент DITA (таблицы и топики) в конечные форматы.
  • Rational Software Architect: всеобъемлющая интегрированная среда разработки для визуального проектирования, конструирования, тестирования, профилирования и развертывания приложений.
  • Rational Application Developer for WebSphere Software: дополните Eclipse функциями визуальной разработки.
  • IBM WebSphere Studio: исследуйте мощную и популярную IDE J2EE от IBM.
  • IBM WebSphere Studio Site Developer for Java IDE Java для Windows и Linux.
  • сайт организации DITA: сведения о DITA, способах создания и редактирования файлов DITA и о других XML-редакторах, поддерживающих DITA.
  • Java EE 5 JDK: упрощает разработку приложений и повышает производительность труда благодаря простой модели программирования.
  • Eclipse Classic for Windows: важный инструментом разработки.
  • IBM Rational Developer: полная среда разработки для традиционных приложений IBM i.
  • DITA Toolkit source files (DITA-OT1.4_src.zip): исходные файлы DITA Toolkit прямо с веб-сайта SourceForge.
  • DITA Open Toolkit: инструментарий для преобразования контента DITA (таблиц и топиков) в конечные форматы.
  • GNU General Public License: распространяйте и модифицируйте свободное программное обеспечение DITA Open Platform на этих условиях, опубликованных организацией Free Software Foundation.
  • DITA Java API Specialization apiref-0.8: скачайте и используйте этот плагин.
  • DITA Java API Specialization Javaapiref-0.8: скачайте и используйте этот плагин.
  • Техническая библиотека по XML: широкий спектр технических статей и советов, руководств, стандартов и документации IBM в разделе портала developerWorks, посвященном XML.
  • Пробное ПО IBM для оценки продуктов: ознакомительные программные продукты IBM, доступные для загрузки на developerWorks, включая инструменты разработки приложений и промежуточное ПО DB2®, Lotus®, Rational®, Tivoli® и WebSphere®
  • Подкасты developerWorks: интересные интервью и дискуссии разработчиков программного обеспечения.

Комментарии

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

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=XML, Технология Java, Rational, WebSphere
ArticleID=1001529
ArticleTitle=Создание справочной документации API Java DITA с использованием DITADoclet и специализации DITA API
publish-date=03172014