спецификации, руководства, описания, API

Новые функции и возможности в Javadoc 5.0

Этот документ описывает изменения, произведенные в инструменте Javadoc между версиями 1.4.2 и 5.0 (прежде 1.5.0).

Упомянутые ниже изменения включают число ошибки и была ли фиксация во фронтэнде инструмента Javadoc ("инструмент") или стандарт doclet ("stddoclet"). Термин "регресс" появляется для функций, которые возвращались в некоторый момент - обычно для функций, которые работали в 1.3.x, ворвались 1.4.x, и были фиксированы в 5.0.

Известные Новые Функции
Известные Исправления ошибок
Известные Ошибки
Несовместимости с Пользовательским Doclets
Новые Функции и Исправления ошибок

Известные Новые Функции

Обобщения, перечисления, и varargs: Добавленная поддержка этих новых функций языка в javadoc фронтэнде инструмента (API Doclet) (4421066, инструмент) и стандарт doclet (4789689, stddoclet, 1 голосование)
Аннотации: Добавленная поддержка аннотаций и аннотации вводит javadoc фронтэнд инструмента (API Doclet) (4904495, инструмент) и стандарт doclet (4905985, stddoclet)
BreakIterator: Мы удалили-breakiterator предупреждающие сообщения от 5.0, и оставили алгоритм повреждения предложения значения по умолчанию неизменным от более ранних выпусков. Таким образом,-breakiterator опция не является значением по умолчанию в 5.0, и при этом мы не ожидаем, что это станет значением по умолчанию. Это - реверсирование от нашего прежнего намерения, что значение по умолчанию изменилось бы в "следующей главной версии" (5.0). Это означает, не изменили ли Вы свой исходный код, чтобы устранить breakiterator предупреждения в 1.4.x, тогда Вы ничего не должны сделать, и предупреждения уйдут в 5.0. Причина этого реверсирования состоит в том, потому что любое преимущество к наличию-breakiterator становится значением по умолчанию, был бы перевешен несовместимым исходным изменением, которого это потребует. Мы сожалеем о любой дополнительной работе и беспорядке, который это вызвало. (-breakiterator опция была добавлена в 1.4.0; для английской локали только, это вынуждает использование BreakIterator class определить, где первое предложение в комментарии документа концы, как BreakIterator уже делает для других языков.) (4959985, инструмент)
Кроме того в будущем выпуске (мы надеемся, 5.1) мы добавим новые теги javadoc (запрос новых функций 4921374), чтобы позволить Вам отметить сводки явно и избегать использования эвристики любого вида.
Новые теги {@literal} и {@code} тег {@literal} обозначают обычный текст. Прилагаемый текст интерпретируется как не содержащий разметку HTML или вкладывается теги javadoc. Например, текст комментария документа: {@literal ac} выводит на экран в сгенерированной неизменной странице HTML: ac - то есть,  не интерпретируется как полужирный.
Тег {@code} форматирует обычный текст в шрифте кода; {@code abc} эквивалентен <code>{@literal abc}</code>.
Тег {@value аргумент}: Этот встроенный тег теперь принимает имя элемента программы: {@value package.class#field}. Это позволяет этому использоваться в любом комментарии документа, не только в комментарии документа постоянного поля. (4764045, stddoclet, 2 голоса)
пакет-info.java: можно теперь создать исходный файл с этим именем, чтобы сохранить комментарии пакета и аннотации. Это может использоваться вместо package.html (который поддерживает только комментарии, не аннотации). Если package-info.java присутствует, javadoc должен проигнорировать package.html и вместо этого ищите комментарий документа пакета, сразу предшествующий (возможно аннотируемый) объявление пакета. javadoc инструмент обрабатывает выбор и парсинг package-info.java и package.html и передает комментарии документа к doclet. См. Package Comment Files.
Аннотация @Deprecated: Это - новая аннотация в 5.0, который должен использоваться в дополнение к @deprecated тег для того, чтобы осудить элементы программы. Спецификация языка Java теперь требует, чтобы компиляторы выпустили предупреждения когда @Deprecated аннотация (но не обязательно тег) используется. @deprecated тег обеспечивает место, чтобы описать то, что заменяет осуждаемый элемент программы. См. Аннотация @Deprecated.
Стандарт doclet перереализация - стандарт doclet и MIF doclet был повторно реализован, чтобы совместно использовать так много кода насколько возможно. Это позволило сократить количество ошибок и в doclets и повысить возможности MIF doclet к тому из стандарта doclet. (Новый MIF doclet еще не был выпущен - это, вероятно, назовут Бетой 1 версии 1.4.) Основная причина мы объединились, эти два doclets то, потому что они оба попытка генерировать по существу тот же самый документ, но в различных форматах (HTML и PDF). (4638723, stddoclet, 2 голоса)
Мы планируем опубликовать этот совместно используемый код как doclet инструментарий, как описано на домашней странице Инструмента Javadoc.
Все новые функции упоминаются ниже.

Известные Исправления ошибок

Опция - тег: Фиксированный (регресс) - тег так его имя может еще раз содержать тире "-", поскольку это позволило в 1.4.1. (4920381, stddoclet, 59 голосов)
Зависните из-за {@inheritDoc}: Больше не зависает, когда {@inheritDoc} (1) не может наследоваться, или (2) наследовался от суперсуперинтерфейса. (4812240, stddoclet, 18 голосов)
Тег @param: Фиксированный @param (регресса) так название параметра (первый параметр) печатается, даже если неправильный, поскольку это работало в 1.3.1. (4802275, stddoclet, 1 голосование)
Тег {@value}: Используя {@value} в пользовательском теге больше не генерирует NullPointerException. (4821796, stddoclet, 1 голосование)
Полоса прокрутки браузера: Internet Explorer больше не выводит на экран ненужную горизонтальную полосу прокрутки, когда фреймы показывают. (4852280, stddoclet, 5 голосов)
Наследование частных на пакет документов: Когда - частная опция используется, теперь должным образом методы документов, наследованные от частных на пакет классов только в наследованной сводной таблице метода а не в разделе детали. (4780441, stddoclet, 5 голосов)
Первое предложение, заканчивающееся {@inheritDoc}: конец первого предложения, содержащего {@inheritDoc}, теперь определяется правильно. (4767038, stddoclet, 4 голоса)
Неработающая ссылка первого предложения с {@docRoot}: первое предложение, содержащее {@docRoot}, ссылка больше не прерывается единственная страница, индексирует. (4760191, stddoclet, 3 голоса)
Наследованная ссылка комментария: наследованный комментарий теперь соединяется непосредственно с надлежащим элементом, не только к class. (4368820, stddoclet, 1 голосование)
Алфавитный индексируют сортировку: Индексируйте сортировку, снова независимо от случая. Только в 1.4.1 и 1.4.2 это был сортированный верхний регистр тогда нижний регистр. (4984419, stddoclet, никакие голоса)
Все исправления ошибок упоминаются ниже.

Известные Ошибки

У Javadoc 5.0 нет никаких известных ошибок, которые заставляют его зависать или отказывать. Можно просмотреть списки от нашей Базы данных Ошибки. Известные ошибки:

Шестикратное ухудшение производительности с тех пор 1.4.2 для глубоко наследованных классов. Замедление происходит частично из-за дополнительной обработки, требуемой универсальными параметрами типа.
Обходное решение: Ни один. (5081166)
@param в основном class игнорируется если {@inheritDoc} в основном описании.
Обходное решение: Ни один. (4778311)
Производит дефектную страницу Постоянных величин, если константа содержит угловую скобку' <'
Обходное решение: Ни один. (5077317)
Уродливый HTML-тэг бросает ошибку, должную обмениваться сообщениями не найденный в файле ресурсов.
Сообщение об ошибке: java.util.MissingResourceException: Can't find resource for bundle com.sun.tools.doclets.formats.html.resources.standard, key doclet.malformed_html_link_tag
Обходное решение: Сократите количество пакетов и классов, которые передают в javadoc, пока ошибка не уходит, и Вы определяете местоположение исходного файла, который содержит уродливый тег. Затем фиксируйте уродливый тег. Уродливый HTML-тэг является тем, который начинается должным образом, но является иначе неподходящим. Например <action> интерпретируется как уродливый тег <a>. (5082928)

Несовместимости с Пользовательским Doclets

У пользовательского doclets, записанного до 5.0, будут проблемы совместимости, когда работавший исходные файлы, которые используют новые функции языка в 5.0.

Новые Функции Языка: API Doclet и стандарт doclet были пересмотрены, чтобы обработать новые 5.0 функций языка - обобщения, перечисления, varargs и аннотации. Чтобы обработать эти функции, пользовательский doclets должен был бы также быть пересмотрен.
Попытки инструмента Javadoc - по мере возможности - чтобы представить так называемое "наследство" doclets с целью программы, которая 1) продолжает работать с пред5.0 исходными кодами, и 2) соответствует их ожидания 5.0 исходных кодов. Так, например, введите параметры и введите параметры, разделяются от универсальных конструкций, вводят переменные, и подстановочные типы заменяются их стираниями, и ClassDoc.fields() возвратит перечислимые константы.

Но поддержка наследства не определяется с точностью. Это - режим эмуляции, который будет достаточен, пока doclet не будет обновлен, чтобы понять язык, на котором это работает. Единственная гарантия является источником и совместимостью на уровне двоичных кодов doclets непосредственно: при использовании 5.0 инструментов Javadoc, если Ваш doclet основан на 1.4 и исходный код, на котором Вы работаете, также основано на 1.4, тогда можно все еще скомпилировать doclet, и это будет все еще работать как прежде (исправления ошибок по модулю).

Новые Функции и Исправления ошибок

Следующее является списком по существу всех новых функций и исправлений ошибок в 5.0. Только очень незначительные изменения опускаются (такие как фиксация неработающих ссылок в документации для API Doclet) и ошибки, представленные в выпусках раннего доступа 5.0, но фиксировали в заключительном выпуске, опускаются.

Параметры командной строки

Новая функция: Новый - опция ключевых слов добавляет HTML meta теги к каждому сгенерированному файлу, чтобы помочь с поиском (4776637, stddoclet)
Новая функция: Новая-notimestamp опция подавляет скрытую метку времени, встроенную около вершины страниц HTML (4777717
Новая функция: теперь возможно создать тестовые подпакеты, которые содержат дефисы, через которые-subpackages опция перескочит, не производя предупреждения. Таким образом, эта опция больше не будет предупреждать, если она встретится с каталогом с недопустимым именем Java (который является непротиворечивым с недопустимыми исходными именами файлов). (4773013, инструмент)
Исправление ошибки: - опция справки больше по ошибке показывает" [имена классов]" в использовании. (4775743, инструмент)
Исправление ошибки: - групповая опция больше не вызывает двойное предупреждение. (4924383, stddoclet)

Tags и Taglets

Новая функция: {@literal} тег обозначает обычный текст. Прилагаемый текст интерпретируется как не содержащий разметку HTML или вкладывается теги javadoc. Например, текст комментария документа: {@literal c} выводит на экран в сгенерированной неизменной странице HTML: c - то есть, не интерпретируется как полужирный.
Новая функция: {@code} тег форматирует обычный текст в шрифте кода. Это эквивалентно, чтобы <кодировать> {@literal} </код>.
Новая функция: {@value} встроенный тег теперь принимает имя элемента программы и метки: {@value package.class#member label}. Это позволяет этому использоваться в любом комментарии документа. (4764045, stddoclet)
Новая функция: Не тег Javadoc, @Deprecated аннотация нова в 5.0 и должна использоваться в дополнение к @deprecated тег для того, чтобы осудить элементы программы. См. @Deprecated аннотацию.
Исправление ошибки: (regresion): Фиксированный @param так название параметра (его первый параметр) печатается, даже если неправильный, поскольку это работало в 1.3.1. (4802275, stddoclet)
Исправление ошибки: Фиксированный (регресс) - тег так его имя может еще раз содержать тире "-", как был позволен в 1.4.1. (4920381, stddoclet)
Исправление ошибки: первое предложение, содержащее {@docRoot}, ссылка больше не прерывается единственная страница, индексирует. (4760191, stddoclet)
Исправление ошибки: конец первого предложения, содержащего {@inheritDoc}, теперь определяется правильно. (4767038, stddoclet, 4 голоса)
Исправление ошибки: Использование {@docroot} тег в - нижний текст больше не вызывает неработающую ссылку на help-doc.html страница. (4851991, stddoclet)
Исправление ошибки: Измененные taglet кодируют, чтобы позволить автономным тегам обрабатывать встроенные теги. (4654308, stddoclet)
Исправление ошибки: Использование {@value} в пользовательском теге больше не генерирует NullPointerException. (4821796, stddoclet)
Исправление ошибки: Встроенные теги теперь позволяют вложенные фигурные скобки, которые не принадлежат встроенным тегам. (4965490, инструмент)
Исправление ошибки: @param, @return и некоторые теги @throws теперь наследовали комментарии должным образом. (4915434, stddoclet)
Исправление ошибки: документация @throws теперь автонаследована, если исключение проверяется. (4947455, stddoclet)

Ссылки

Исправление ошибки: наследованный комментарий теперь соединяется непосредственно с надлежащим элементом, не только к class. (4368820, stddoclet)
Исправление ошибки: сводный заголовок больше не отсутствует, когда class не имеет никаких прямых элементов, но наследовал элементы. (4904036, stddoclet)
Исправление ошибки: Относительная ссылка в <href> в первом предложении больше не генерирует неработающую ссылку, когда это появляется на других страницах. (4460354, stddoclet)
Для большего количества исправлений ошибок ссылки см. "Tags и Taglets", связался с {@docRoot} тег.

Задокументированные Исходные файлы

Новая функция: package-info.java зарезервированное имя для исходного файла, чтобы сохранить комментарии пакета и аннотации. package-info.java описывается выше.

Сгенерированные Спецификации API

Новая функция: Добавленная поддержка обобщений, перечислений, и varargs в javadoc фронтэнде инструмента (API Doclet) (4421066, инструмент) и стандарт doclet (4789689, stddoclet)
Новая функция: Добавленная поддержка аннотаций и аннотации вводит javadoc фронтэнд инструмента (API Doclet) (4904495, инструмент) и стандарт doclet (4905985, stddoclet)
Новая функция: Для четкости постоянные значения полей типа долго теперь печатаются с "L", а не нижним регистром "l". (4869993, инструмент)
Новая функция: Для четкости, serialVersionUID значения типа долго теперь печатаются с "L", а не нижним регистром "l". (4821483, stddoclet)
Новая функция: Оглавление было добавлено к вершине "Осуждаемого" списка. (4927552, stddoclet)
Исправление ошибки: Больше не зависает, когда {@inheritDoc} (1) не может наследоваться, или (2) наследовался от суперсуперинтерфейса. (4812240, stddoclet)
Исправление ошибки: Наследованный непубличный суперкласс больше не упоминается (4874845, stddoclet)
Исправление ошибки: "Определенный:" и "Переопределения:" комментарии теперь наследованы от классов, на которые внешне ссылаются. (4857717, stddoclet)
Исправление ошибки: Документация больше не наследована от элементов частных на пакет классов. (4780441, stddoclet)
Исправление ошибки: Порядок описаний метода больше не может измениться от одного выполнения до следующего. (4885372, stddoclet)
Исправление ошибки: Когда class B расширяет class, который реализует интерфейс I в документации, поскольку я, мы теперь документ, который B реализует I (под "Всеми классами с реализацией"). (4947464, stddoclet)
Исправление ошибки: Корректный тип возврата теперь обнаруживается в задействованной сводке, когда метод наследовал документацию от переопределенного метода, который возвращает различный тип. (4951228, stddoclet)
Исправление ошибки: Теперь генерирует документ для readObjectNoData () в сериализированной странице формы. (4770063, stddoclet)
Исправление ошибки: Теперь генерирует сводную страницу пакета для неназванного пакета, если существующий. (4774450, stddoclet)
Исправление ошибки: Теперь печатные издания, "Неназванные" как имя неназванного пакета, вместо того, чтобы печатать пустую строку. (4904075, stddoclet)
Исправление ошибки: Все наследованные методы от многократных расширенных интерфейсов теперь документируются. (4933335, stddoclet)
Исправление ошибки: методы Interface больше не отмечаются "общественность" (только изменение - не фактически ошибка). (4682448, stddoclet)
Исправление ошибки: комментарии Конструктора теперь располагаются с отступом должным образом. (4904037, stddoclet)
Исправление ошибки: packages.html (отмечают множественное число) файл больше не включается, поскольку это не использовалось или нуждалось с тех пор 1.1. (4475679, stddoclet)
Исправление ошибки: Когда параметр типа в задействованной сводке больше чем 10 символов, теперь добавьте разрыв строки, чтобы сократить это (4927167, stddoclet)

Форматирование и Недопустимый HTML

Исправление ошибки: Теперь выводы <NOSCRIPT> тегируют с каждым <СЦЕНАРИЙ> тег. (4855054, stddoclet)
Исправление ошибки: Internet Explorer больше не выводит на экран ненужную горизонтальную полосу прокрутки, когда фреймы показывают. (4852280, stddoclet)
Исправление ошибки: Новые строки больше не трудно кодируются как "\n". (4938109, stddoclet)
Исправление ошибки: Табличная граница добавила вокруг заголовков class в сводке постоянной величины. (4904025, stddoclet)
Исправление ошибки: Теперь печатает определенные исходные комментарии HTML условно (4904038, stddoclet)

Панель навигации

Исправление ошибки: дополнительный столбец больше не появляется в первой строке navbar. (4664607, stddoclet, 1 голосование)
Исправление ошибки: ссылка Пакета является теперь активной, документируя только один пакет. (4689286, stddoclet)
Исправление ошибки: следующие/Предыдущие ссылки Класса теперь выполняют итерации через все интерфейсы и классы в текущем пакете. (4131628, stddoclet)

Доступность

Исправление ошибки: Табличные заголовки теперь используют

. (4905786, stddoclet)

Исправление ошибки: Без вести пропавшие пространства добавили в конце альтернативного текста для inherit.gif. (4956908, stddoclet)

Выполнение Javadoc

Исправление ошибки: Больше не получите InvocationTargetException, когда источник flie соединяется с другим исходным файлом в неправильном каталоге. (4835749, stddoclet)
Исправление ошибки: (регресс) Больше не перестал работать на внутренних классах, поскольку он работал в 1.4.1. (4843578, инструмент)

Ошибочные/Предупреждения/Уведомления сообщения

Новая функция: Теперь предупреждает, когда тег @return присутствует в пустом методе. (4490068, stddoclet)
Новая функция: Теперь дисплеи обмениваются сообщениями, создавая новый целевой каталог (4657239, stddoclet)
Исправление ошибки: предупреждения BreakIterator больше не появляются. Для получения дополнительной информации см. выше. (4959985, инструмент)
Исправление ошибки: "первое предложение", больше, предупреждающее не разделяется между stderr и stdout. (4753853, инструмент)
Исправление ошибки: реализация DocLocale.java была изменена, чтобы учесть надлежащее преобразование. (4780921, инструмент)
Исправление ошибки: Теперь использование DocletErrorReporter, чтобы напечатать ошибки опции, а не MessageRetriever. (4927928, stddoclet)
Исправление ошибки: сообщение больше не говорит "ошибку", когда это - действительно предупреждение для недостающего файла списка пакета. (4625883, stddoclet)

API Doclet

Новая функция: Добавленная поддержка обобщений, перечислений, и varargs в javadoc фронтэнде инструмента (API Doclet) (4421066, инструмент) и стандарт doclet (4789689, stddoclet)
Новая функция: Добавленная поддержка аннотаций и аннотации вводит javadoc фронтэнд инструмента (API Doclet) (4904495, инструмент) и стандарт doclet (4905985, stddoclet)
Новая функция: метод Add Doclet.languageVersion, чтобы определить, для которого была записана версия исходного кода Java doclet. (4909767, инструмент)

Стандартная Реализация Doclet

Исправление ошибки: повторно реализованный стандарт doclet, чтобы максимизировать совместно использованный код для doclets эмуляция stddoclet (4638723, stddoclet)

Свяжитесь с Нами