Этот документ описывает изменения, произведенные в Javadoc между версиями 1.1 и 1.2. Это делится на разделы для трех типов пользователей: (1) для писателей комментариев документа, (2) для разработчиков, желающих записать doclets (архитектура и API Doclet), и (3) для читателей javadoc-сгенерированных страниц HTML (контент и формат). Более подробная информация дается в "Подробных Изменениях" раздел, который следует.
СВОДКА ИЗМЕНЕНИЙ
Эта сводка включает изменения для писателей комментариев документа, изменяется на инструмент Javadoc (API Doclet) и изменяется на контент и формат вывода HTML Javadoc (как реализовано в Стандартном Doclet).
Следующий список суммирует в одном месте все функции, перечисленные в другом месте, который может оказать влияние на то, как Вы записали бы комментарии документа.
Первое предложение каждого описания class должно быть сводным оператором.
Комментарии на уровне пакета теперь возможны.
Первое предложение каждого описания пакета должно быть сводным оператором.
В масштабе всей системы (краткий обзор) комментарии теперь возможны.
Новые теги Javadoc доступны для использования в комментариях документа.
Копирует новый каталог "файлов документа" для содержания изображений и примеров.
Иерархическая целевая файловая структура
Возможные несовместимости между 1.1 и 1.2 комментариями документа
Представляет опции для того, чтобы добавить уникальный title, заголовок, нижний колонтитул, и подстрочное примечание. Подстрочное примечание для информации как ссылка mailto и уведомление об авторском праве.
Больше не полагается на изображения для заголовков и маркеров. Вместо этого это использует табличные ячейки и горизонтальные правила отличить заголовки и API.
У Javadoc теперь есть API Doclet, в который можно записать doclets. Это - главное архитектурное изменение к Javadoc. Можно использовать Javadoc doclets, чтобы настроить вывод Javadoc. Думайте о doclet как о плагине для текстового преобразования. doclet пишется doclet API к, определяет контент и формат вывода, который будет сгенерирован инструментом Javadoc. Можно записать doclet, чтобы генерировать любой вид вывода текстового файла, такого как HTML, SGML, XML, RTF, и MIF. Sun обеспечивает "стандарт" doclet для того, чтобы он генерировал документацию API формата HTML. Doclets может также использоваться, чтобы выполнить специальные задачи, не связанные с созданием документации API. Например, диагностика doclet могла быть создана, чтобы проверить, что у всех элементов есть комментарии для документации.
Побуждение для Новой Архитектуры - исходный Javadoc (в 1.0.x и 1.1.x) берет исходные файлы java так ввод и производит HTML как выходной. Формат вывода HTML трудно кодируется в java. Недостаток - то, что разработчики, которые хотят настроить вывод, являются неудачливыми, если они не имеют исходную лицензию и хотят взломать некоторый очень тайный код. Это означает, что технические писатели не могут сделать улучшения, в которых они, возможно, нуждались бы, ли незначительный (такие как написание прописными буквами слово, изменяя цвет, добавляя полужирный...) или главный (преобразовывающий в новый формат, такой как MIF или RTF).
Требования для перепроектирования Javadoc были:
Разделите механизмы, используемые, чтобы проанализировать и обработать входной источник от спецификации выходного формата.
Сделайте выходную спецификацию формата сменной.
Сделайте выходную спецификацию формата настолько постижимой насколько возможно техническим писателям.
Новая архитектура: javadoc фронтэнд обрабатывает параметры командной строки и парсинг/обработку java, создавая корневую структуру данных и выдает это к java "doclet". doclet получил бы доступ к этим данным через API, представляющий пакеты, классы, методы, поля, и комментарии, так же как перечисления этих объектов. Новый doclets мог быть записан этому API, или стандарт doclets мог быть разделен на подклассы, чтобы позволить незначительные изменения.
КОНТЕНТ - НОВЫЕ ТЕГИ
Эти теги фактически реализуются в javadoc API, не в стандарте doclet.
Новый тег "@throws" является синонимом для "@exception". Это - удобство, так как "броски" являются ключевым словом на языке Java.
Существующий тег "@see" теперь принимает пакеты, привязки HTML и заключенные в кавычки строки. Это может также взять метку. Тег @see может обратиться к пакету точно так же, как он может обратиться к class, методу или другому API. Привязка HTML имеет форму <a href="xxx">XXX</a> и заключенная в кавычки строка имеет форму "xxx". Для примеров см. Ссылочную Страницу Javadoc. Метка является дополнительной и имеет форму: " этикетка @see". Если метка будет включена, то она будет выведена на экран вместо имени.
Новый тег" {@link apiname метка}" для встроенных ссылок в тексте. В предыдущих версиях Javadoc единственный способ включать ссылки к API состоял в том, чтобы использовать тег @see или для HTML твердого кода. Этот новый встроенный тег использует тот же самый алгоритм что использование @see, чтобы генерировать ссылку HTML. Различие - то, что это помещает встроенную ссылку, а не под "См. Также" заголовок.
КОНТЕНТ - ПРЕДОСТАВЛЯЕТ БОЛЬШЕ ИНФОРМАЦИИ О API И ССЫЛОК
Добавьте к исходному дереву один файл на пакет, названный "package.html", выделенный комментариям документа. Первое предложение каждого описания пакета является сводкой. Javadoc поднимает все между <телом> и </тело>, и добавьте это к сводной странице пакета "package-summary.html" (который также содержит таблицу ее классов и интерфейсов). Джейвэдок копирует первое предложение этого к странице краткого обзора "overview.html". Поэтому, недопустимо поместить title или любой другой текст между <телом> и первым предложением. Схема для комментариев на уровне пакета:
Введение
Спецификация пакета
Связанная Документация
Для получения дополнительной информации см. .
Старое Поведение: у Javadoc 1.1 нет никакого механизма для включения комментариев, определенных для определенного пакета. ОТМЕТЬТЕ - вышеупомянутая функция требует, чтобы писатели следовали за новым правилом Javadoc: первое предложение каждого описания пакета должно быть сводным оператором.
Добавьте единственный документ в масштабе всей системы "overview.html" для набора пакетов. Включайте в это любые комментарии, которые применяются ко всем задокументированным пакетам. Например, Вы могли бы задокументировать следующее предположение на этой странице: "NullPointerException бросается везде, где в нуле передают, за исключением отмеченного." Этот файл принадлежит в Вашем исходном дереве и может быть любым именем файла, которое Вы определяете. Условно, мы используем имя "overview.html". Определите это имя файла с - опция краткого обзора на командной строке, выполняя Javadoc и содержание файла (между <тело> и </тело> теги) вставляется в начальную страницу, которая появляется в правом фрейме, названном overview-summary.html (который вызвали packages.html в Beta3 и более ранних версиях).
Старое Поведение: у Javadoc 1.1 нет никакого механизма для включения комментариев, которые применяются ко всем пакетам.
Javadoc поднимает первое предложение короткая сводка для каждого пакета от package.html и вставляет это packages.html. Это обеспечивает, краткая сводка каждого упаковывает в списке всех пакетов.
Старое Поведение: у Javadoc 1.1 нет такого сводного списка.
Поднимите первое предложение каждого описания class и включайте это в сводку class в package-<class>.html, Это обеспечивает краткую сводку всех классов для данного пакета.
Старое Поведение: у Javadoc 1.1 нет такого сводного списка. ОТМЕТЬТЕ - вышеупомянутая функция требует, чтобы писатели следовали за новым правилом Javadoc: первое предложение каждого описания class должно быть сводным оператором.
Добавьте наследованный API к методу и полевым сводкам на страницах интерфейса и class.
Старое Поведение: В Javadoc 1.1, наследованные элементы для данного class не появляются на странице class, требуя ссылок, чтобы обнаружить их.
Включайте тип возврата и ключевые слова, "статичные", "защищенные" и "краткий обзор" в подписи в сводке метода, так как они необходимы кому-то, вызывая метод. Не включайте общественность, переходный процесс, энергозависимый, или заключительный; те появляются в разделе детали далее ниже на страницу. Включайте тип данных полей.
Старое Поведение: В Javadoc 1.1, сводки метода не указывают на тип возврата. Полевые сводки не указывают на тип поля.
Добавьте "Определенный" для элементов, которые реализуют интерфейс.
Старое Поведение: В Javadoc 1.1, элементы class, которые реализуют интерфейс, не делают такого упоминания.
Добавьте список подклассов наверху страницы class. Также добавьте подынтерфейсы и классы с реализацией наверху страниц интерфейса.
Старое Поведение: Javadoc 1.1 не перечисляет подклассы на странице class.
Скопируйте описание автоматически с метода в интерфейсе к его подклассу реализации только, когда метод реализации не содержит текста. Включайте шаблонный оператор, который говорит, что текст копируется с интерфейса. Причина выполнения этого, то, что, реализовывая интерфейс, описания метода часто идентичны и для интерфейса и для class. Копирование описаний вручную походит на бесполезную работу, которую трудно поддержать.
Старое Поведение: Javadoc 1.1 не копирует описания метода с интерфейса.
Добавьте структурный вид для каждого пакета. Когда Вы просматриваете пакет или class, "Древовидная" ссылка идет в то представление, у которого тогда есть ссылка к дереву для всех пакетов.
Старое Поведение: у Javadoc 1.1 нет никакого структурного вида (иерархия class) единственных пакетов. Единственный структурный вид имеет все пакеты, который, для JDK, является подавляющим.
Представьте - опция ссылки для того, чтобы соединиться с внешними Javadoc-сгенерированными документами. Значение по умолчанию не должно соединиться с внешней документацией. Когда кто-то генерирует документы, - опция ссылки генерирует ссылки к документации для любого API, на который ссылается задокументированный API. Ссылки могут быть локальными или удаленными (в Интернете).
Старое Поведение: Javadoc 1.1 не делает ссылок к документации снаружи, что сгенерировано.
Представьте ошибки против конструкторов по умолчанию, которые не должны быть задокументированы Javadoc. Мы должны или осудить их или удалить их как ошибки. (Не влияет на Javadoc),
Старое Поведение: Javadoc включает всех конструкторов по умолчанию, вызывал ли бы разработчик приложений когда-либо их. Когда это документирует конструкторов по умолчанию, это оставляет их незаполненные описания.
Добавьте осуждаемую сводную страницу, перечисляющую весь осуждаемый API. (В конечном счете мы добавим ссылки к заменяющему API.)
Старое Поведение: Javadoc 1.1 не генерирует список осуждаемого API.
Классы Марка, которые осуждаются.
Старое Поведение: В Javadoc 1.1, осуждаемые классы не отмечаются как таковые в списке class для данного пакета.
Удалите "синхронизировался" и "собственный" от подписей. Javadoc генерирует спецификацию API. Эти два ключевых слова не принадлежат в подписях спецификации, потому что они специфичны для реализации. "Собственное" ключевое слово не должно быть задокументировано. "Синхронизируемое" ключевое слово указывает на ориентированное на многопотоковое исполнение поведение, которое должно вместо этого быть описано в описаниях метода. Сам ориентированный на многопотоковое исполнение метод не мог бы использовать "синхронизируемое" ключевое слово, но мог бы вызвать закрытые методы, которые являются.
Старое Поведение: Javadoc 1.1 включает ключевые слова, "синхронизируемые" и "собственные".
Скопируйте каталог "файлов документа" (один на пакет) для содержания изображений и примеров. Джейвэдок ищет каталог, названный "файлами документа" в каждом каталоге пакета исходного дерева, и копирует тот каталог и его содержание месту назначения. Файлы в "файлах документа" просто копируются в место назначения и не обрабатываются Javadoc. Это означает, что эти файлы не могут содержать стандартную панель навигации, заголовок или нижний колонтитул, или быть включены в индексирование или дерево. Этот каталог может содержать произвольные файлы, на которые ссылаются комментарии документа. Примеры: изображения, файлы HTML, текстовые файлы, исходный код в качестве примера, HTML-таблицы совместно используются больше чем одним class. Пример: включать ссылку на файл изображения "Кнопка-1.gif" в пределах описания для java.awt. Кнопка class:
В исходном дереве создайте каталог, названный "файлами документа" в "java/awt /" каталог.
Поместите файл "Кнопки-1.gif" в каталог "файлов документа".
Добавьте <img> тег к своему комментарию документа для Кнопки class:
/**
* <img src="doc-files/Button-1.gif">
*/
Программное обеспечение Java приняло соглашение о присвоении имен, запускающееся с "-1" и постепенно увеличивающееся для последующих изображений. Для получения дополнительной информации см. .
Старое Поведение: В Javadoc 1.1, выполняя Javadoc генерирует файлы с неработающими ссылками, потому что изображения не копируются в место назначения. (В JDK эти изображения являются в настоящий момент главным образом снимками экрана компонентов Swing и AWT.)
Добавьте-title опцию, чтобы включать title в первую страницу "packages.html". Пример title: "Платформа Java 1.2 Базовых API".
Старое Поведение: у Javadoc 1.1 нет никакого формального способа добавить title к сгенерированному документу.
Добавьте - заголовок, футов длиной, - нижние опции для заголовка/нижнего колонтитула/нижней части на каждой странице. Это позволяет Вам поместить номер версии API (такого как "Java 1.2 Беты 4") на каждой странице так, чтобы, когда Вы распечатываете страницу, у Вас была запись версии, из которой это прибыло. "Нижняя" функция позволяет Вам добавлять уведомление об авторском праве или ссылку электронной почты обратной связи у основания каждой страницы.
Старое Поведение: В Javadoc 1.1, номер версии по умолчанию не появляется ни на какой странице.
КОНТЕНТ - НИКАКИЕ ССЫЛКИ ИСХОДНЫЕ ФАЙЛЫ TO
Для внутренней разработки, имея прямые ссылки от каждой Javadoc-сгенерированной страницы class до ее исходного кода было бы удобно. Однако, мы решили не включать ссылки в документацию API Java к исходному коду Java, когда мы генерируем и публикуем нашу документацию API. Следовательно это becamse низкий приоритет, чтобы поместить ту функцию в стандарт doclet. Однако, мы сделали доступным отдельно .
ФОРМАТ - ФАЙЛЫ ИЗОБРАЖЕНИЙ
Устраните любой потребовал изображений ДЖИФА. Замените маркеры ДЖИФА горизонтальными правилами. Замените графические заголовки (например, "Методы", "Поля") с текстом в цветных табличных ячейках.
Старое Поведение: Javadoc 1.1 требует изображений ДЖИФА для маркеров и заголовков. Они не необходимы, они замедляют дисплей, и они должны быть вручную скопированы в место назначения.
ФОРМАТ - ТАБЛИЦА СТИЛЕЙ
Добавьте таблицы стилей HTML для управления цветов, шрифтов и расположения. Таблицы стилей являются стандартизованным способом выбирания цветов, шрифтов и расположения текста на веб-страницах во времени выполнения. Чтобы изменить цвета табличных ячеек или размеров шрифта в левых фреймах, измените файл stylesheet.css это сгенерировано javadoc. Есть также-stylesheetfile опция, работая javadoc для того, чтобы определить Вашу собственную таблицу стилей. Например, можно изменить фоновый цвет ячейки заголовков от темно-синего до белого, редактируя файл stylesheet.css следующим образом. От:
#TableHeadingColor { background: #CCCCFF } /* Dark mauve */
К:
#TableHeadingColor { background: #FFFFFF } /* Dark mauve */
Для формального описания см. от W3C. Для более практического описания см. от CNET. (Для введения щелкните "назад к введению" из CSS Таблица ссылок.)
ФОРМАТ - УЛУЧШЕННАЯ НАВИГАЦИЯ
Добавьте фреймы для пакета, class и элемента. (Ни для каких фреймов запустите в "package-summary.html". Для фреймов запустите в "overview-summary.html"),
Старое Поведение: у Javadoc 1.1 нет никакого легкого способа получить доступ к любому пакету, class или элементу. Это требует пользователей к следу.
Добавьте "Все классы" ссылка к вершине списка пакета (верхний левый фрейм). Когда пользователь щелкает по этому, это должно дисплейный список всех классов в алфавитном порядке в более низком левом фрейме.
Старое Поведение: у Javadoc 1.1 нет никакого легкого способа получить доступ к любому class, независимо от пакета, в котором это находится. Это требует, чтобы пользователи пошли в "Иерархию классов". Было бы хорошо иметь список только классов и интерфейсов.
Разработайте единственную панель навигации, которая работает во всех экранах. Затемните неиспользованные элементы.
Старое Поведение: В Javadoc 1.1, стандартная панель навигации вдоль вершины изменяется существенно от страницы до страницы. Есть три различных панели навигации: все пакеты (2 элемента), пакет (3 элемента), и class (6 элементов).
Добавьте другую панель навигации, чтобы перейти к каждому подразделу. Сводка: Внутренний | Поле | Constr | Деталь Метода: Поле | Constr | Метод
Старое Поведение: Javadoc 1.1 требует, чтобы Вы прокрутили мимо описания class, чтобы добраться до задействованных сводок и детали.
Переименуйте "Пользовательское Руководство по API", соединяются со "Справкой". Измените Javadoc, чтобы генерировать справочный файл значения по умолчанию. Добавьте опцию-nohelp, чтобы опустить ссылку "Справки" от панели навигации при желании. Добавьте опцию-helpfile, чтобы создать файл
Старое Поведение: у Javadoc 1.1 есть ссылка в packages.html вызванном "Пользовательском Руководстве по API". Файл, на который это указывает, автоматически не копируется в целевой каталог.
Фрейм HTML для элементов в Javadoc 1.2. Это - функция, к которой мы рассмотрели добавление к стандарту doclet, но решили не. Мы планируем объявить о стороннем разработчике, чтобы в конечном счете выпустить эту функцию в отдельном doclet.
ФОРМАТ - ВЕБ-СТРАНИЦЫ
Измените сводки на таблицы с цветом фона ячейки и границами. Это лучше различает сводку и части детали файлов class.
Старое Поведение: В Javadoc 1.1, оба сводка и части детали оба выглядят довольно подобными, это не очевидно, прокручивая вниз страницу, в каком разделе Вы находитесь.
Сохраните "Индексируют" как имя расположенного в алфавитном порядке списка API в конце документа. Переименуйте главную часть каждой страницы пакета от "Пакета, Индексируют" к "Сводке Пакета", аналогично для главной части каждого class, страница переименовывает "Метод, Индексируют" к "Сводке Метода", "Конструктор Индексирует" к "Сводке Конструктора", и "Поле Индексирует Сводку поля "Кому"".
Старое Поведение: В Javadoc 1.1, слово "индексирует", используется, чтобы идентифицировать обе сводки наверху страниц class, и алфавитный список книжного шрифта, содержащий весь API. Это напрасно сбивает с толку.
ФОРМАТ - ИНДЕКСИРУЕТ УЛУЧШЕНИЯ
Добавьте-breakindex опцию, чтобы повредить индексирование в отдельный файл для каждой буквы алфавита.
Старое Поведение: В Javadoc 1.1, индексирование является гигантским 1.4MB файл для JDK; берет навсегда, чтобы загрузиться по Интернету.
Добавьте классы и интерфейсы к индексированию.
Старое Поведение: В Javadoc 1.1, индексировать списки только конструкторы и элементы, не классы или интерфейсы.
Интернационализируйте индексирование, чтобы включить любым символам Unicode.
Старое Поведение: В Javadoc 1.1, индексировать дескрипторы только алфавит A-Z. (Фактически, только A-Y.)
ФОРМАТ - ИЕРАРХИЧЕСКАЯ ЦЕЛЕВАЯ ФАЙЛОВАЯ СТРУКТУРА
Добавьте иерархические целевые каталоги, который тиражирует дерево исходного кода одного каталога на подпакет. Плоская структура больше не будет поддерживаться. Это имеет эффект сокращения количества файлов в каталоге, распределяя их пакетом. Побочный эффект состоит в том, чтобы уменьшить длину имен файлов, так как имена пакета будут именами каталогов, а не частью имени файла. Это облегчит для третьих сторон генерировать более короткие имена (например, 31-символьные имена для Macintosh), которые сохраняют некоторое значение. Например, java.awt.Button.html теперь будет \java\awt\Button.html Учитывая все 1.2 изменения, целевая файловая структура для того, чтобы выполнить Javadoc на java.applet пакете была бы теперь похожа на файловую структуру.
Старое Поведение: Javadoc 1.1 использования плоская структура, где все файлы HTML находятся в единственном каталоге.
НЕСОВМЕСТИМОСТИ
Возможные несовместимости между 1.1 и 1.2 комментариями документа Мы делали все возможное записать Джейвэдоку 1.2, чтобы быть совместимыми с комментариями для документации, записанными для предыдущих версий Javadoc. Однако, может быть несколько случаев, где старые комментарии для документации, возможно, не "работают" то же самое когда компилирующийся с Javadoc 1.2.
Много имен файлов изменились. Самое важное изменение - то, что начальная страница сгенерированной документации теперь index.html (который устанавливает фреймы HTML) вместо packages.html. Если Вы хотите избежать фреймов, начальная страница, чтобы загрузиться overview-summary.html (который заменяет packages.html в 1.1).
В тексте комментариев писатели, возможно, трудно кодировали встроенные ссылки к именам API. Поскольку javadoc теперь генерирует иерархические каталоги, те ссылки были бы теперь повреждены. Новое {@link} тег включает надлежащим встроенным ссылкам.
ДРУГОЙ DOCLETS
Поддержите Javadoc 1.1 формата с его собственным doclet. Это сохраняет старый взгляд и плоскую структуру каталогов, но с некоторыми из новых исправлений ошибок. Чтобы получить доступ к этому, используйте "-1.1" javadoc опции
Старое Поведение: - Javadoc 1.1 формата важны для тех, кто создал синтаксические анализаторы, которые работают на и полагаются на тот вывод HTML.
[Будущая] Реализация MIF doclet. Это добавит возможность генерировать вывод MIF, для того, чтобы импортировать в FrameMaker. (План сделать и выпустить отдельно после 1.2.)
Старое Поведение: у Javadoc 1.1 нет никакой возможности MIF (Javadoc 1.0.2 делает).
БУДУЩИЕ УЛУЧШЕНИЯ - DO TO В ВЫПУСКЕ ПОСЛЕ 1.2
Учтите инкрементный, создает содействие единственному Javadoc-сгенерированному документу. Было бы полезно, чтобы сохранить промежуточный формат от каждого выполненного Javadoc и позволить объединяться тех промежуточных форматов в полный документ, с полностью корректным индексируют, дерево, иерархия class, список подклассов, и т.д. (Не сделанный - запланированный выпуск после 1.2)
Старое Поведение: Javadoc 1.1 не позволяет инкрементное здание документации.
