Spec-Zone .ru
спецификации, руководства, описания, API
|
|
Spec-Zone .ru
спецификации, руководства, описания, API
|
Этот документ описывает изменения, произведенные в инструменте Javadoc между версиями 1.3 и 1.4. Можно также видеть краткий список выдающихся ошибок, перечисленных в , и можно просмотреть списки от нашей базы данных в .
{@linkplain}, {@inheritDoc}, @serial, {@value}
Новые Опции
-breakiterator, -docfilessubdirs -exclude, -excludedocfilessubdir -nocomment, -noqualifier, -quiet, -source, -linksource, -subpackages, -tag, -taglet
@throws комментарии более консервативно-subpackages опция, чтобы рекурсивно пересечь все подпакеты, передавая в единственном корне пакета. -exclude опция безоговорочно исключает пакеты из списка пакетов к документу, даже если это было бы иначе включено некоторыми предыдущими или позже -subpackages флаг командной строки. Например, -subpackages java -exclude java.lang.ref включал бы java.io, java.util, и java.lang (среди других), но не java.lang.ref. Добавленный"-source 1.4"опция для утверждений - Этот код документов опции, который был скомпилирован, используя"javac -source 1.4", необходимый для кода, который содержит утверждения.
Добавленные открытые методы, чтобы вызвать инструмент Javadoc изнутри Java - Добавленный программируемый интерфейс к инструменту Javadoc в com.sun.tools.javadoc. Основной (следовательно, стандарт doclet был сделан повторно используемым). Для получения дополнительной информации см. Стандартный Doclet.
Предупреждающие сообщения и сообщения об ошибках теперь содержат имя файла и номер строки. Номер строки к строке объявления, а не к определенной строке в комментарии документа. Использование SourcePosition класс.
Сериализированные улучшения страницы формы - Javadoc теперь включает частные классы в сериализированную страницу формы (не требуя -private флаг). Это означает, что сериализированная страница формы может быть должным образом сгенерирована в нормальном выполненном Javadoc. Это было сделано, добавляя метод PackageDoc.allClasses(boolean filter) где частные и частные на пакет классы включаются когда filter ложь. (
) метод writeReplace() теперь включается в сериализированную страницу формы. Javadoc также теперь смотрит на"@serial include"и"@serial exclude"теги и включают или исключают классы соответственно. Для получения дополнительной информации см. @serial тег. (, 4180839, 4341304)
Задокументированный @files чтобы работать с параметрами командной строки так же как именами файлов, Это изменяет документацию, чтобы соответствовать реализации. @files функция была первоначально задокументирована в javadoc и javac, чтобы позволить только имена файлов, не параметры командной строки. Это разворачивает документацию, чтобы сказать это @files также позволяет параметры командной строки. (Также переименованный @files к @argfile в документации, чтобы прояснить это - файл параметров.)
Добавленный -quiet опция, чтобы отключить несообщения об ошибках
Только предупреждения и ошибки кажутся, делая их легче найти.
Стандарт doclet печатает свой номер версии в его потоке вывода. Подавленный -quiet опция.
Автоматически создайте целевой каталог (-d). Так как первичная функция javadoc должна создать файлы и каталоги, кажется разумным создать корневой целевой каталог также.
Документ только юридические классы - документируя пакет, Javadoc больше не читает файлы, имена которых не составляются из юридических имен классов. Пример: передавая com.sun.foo в Javadoc это имело обыкновение анализировать каждый файл в каталоге com\sun\foo чье имя, законченное ".java", было ли имя файла, лишенное того суффикса, фактически юридическим именем класса. Теперь Javadoc проанализирует только файлы, имена которых являются юридическими именами классов. Это позволяет разработчикам включать шаблоны, протестировать исходные файлы, или другие.java файлы, которые не будут задокументированы, включением, например, дефисом "-" в его имени файла.
Фиксированный -linkoffline разделитель '/' - работая на Microsoft Windows, -linkoffline опция теперь должным образом вставляет'/'вместо'\'в каждой ссылке, которая указывает на внешний класс. Вызванные неработающие ссылки этой ошибки на внешние классы, когда документация, которая создавалась Javadoc на Windows, была тогда просмотрена на Unix.
Удаленный транзитный "-1.1" опции -"-1.1" опции были представлены в версии 1.2 как doclet, чтобы обеспечить путь перехода от Javadoc 1.1 к 1.2. Этот переход не необходим для того, чтобы переместиться в 1.3. "1.1" doclet не обрабатывали новые функции языка (такие как внутренние классы), и из-за совместно используемого кода со стандартом doclet был препятствием для обслуживания.
@return, и встроенные теги, подобные {@link}. -tag опция.-taglet и -tagletclasspath опции (не используют -tag опция).-tag и -taglet опции определяют порядок, они выводятся. Можно смешать эти опции со стандартными тегами"-tag return", "-tag param"чтобы вкрапить их. Для пользовательских встроенных тегов следует создать taglet.
Отметьте любые неизвестные теги, печатая пользовательские теги. Это - часть пользовательского механизма тега. Когда javadoc анализирует комментарии документа, любой тег, с которым встречаются, который не является или стандартным тегом или передал в с - тег или-taglet считают неизвестными, и предупреждение бросается.
Опуская ведущую звездочку (*), сохраните добавление отступа в пределах <PRE> теги. Это позволяет Вам вставить примеры кода непосредственно в комментарий документа. Добавление отступа относительно левого поля (а не разделитель /**). ()
Добавленный -breakiterator для нового способа определить конец первого предложения. Мы планируем изменить алгоритм для того, чтобы определить конец первого предложения в следующем выпуске основной функции. -breakiterator опция дает Вам предварительный просмотр нового алгоритма. В 1.2 и 1.3, java.text. Класс BreakIterator использовался, чтобы определить конец предложения для всех языков, но английского языка . У английского языка был свой собственный алгоритм, который искал период, сопровождаемый пространством. Когда -breakiterator опускается, конец первого предложения неизменен от 1.2 и 1.3, но предупреждения испускаются, выводя на экран, где было бы различие. Используя -breakiterator использует новый алгоритм. Различия в алгоритмах обнаруживаются на английском языке следующим образом:
<P>.Фиксированный Javadoc, чтобы больше не потребовать тел метода. - Можно теперь выполнить javadoc на.java исходных файлах, которые являются чистыми тупиковыми файлами без тел метода. Это означает, что можно записать комментарии для документации и выполнить Javadoc на ранних стадиях проекта, создавая API, прежде, чем записать реализацию. Ранее, javadoc жаловался, попытались ли Вы сделать это, настаивая, чтобы Вы добавили "краткий обзор" к методам и классам.
Добавленный {@linkplain}, версия простого текста {@link}. Метка ссылки выводится на экран в шрифте кода, а не простом тексте. Полезный, когда метка является простым текстом.
Пример:
Refer to {@linkplain add() the overridden method}.
Добавленный {@inheritDoc} тег для того, чтобы наследовать документацию. Этот тег копирует комментарий документа с суперкласса в текущий комментарий документа. Это позволяет разработчикам писать вокруг скопированного текста, а не иметь наследованный текст быть единственным текстом. Ранее, текст был скопирован, только если комментарий отсутствовал.
Javadoc тегирует @return, @param, и @throws теперь индивидуально наследованы. В 1.3, они были бы наследованы, только если весь комментарий документа был пуст. Тег @see также наследован, но только если нет никаких тегов @see в элементе переопределения.
@throws документация копируется от переопределенного метода до подкласса только, когда исключение явно объявляется в переопределенном методе. В 1.3, @throws текст был бы скопирован в метод переопределения, мог ли бы тот метод фактически бросить это execption. Это новое поведение может удалить некоторую документацию, которую должным образом наследовал @throws. Можно использовать {@inheritDoc} вызвать @throws наследовать документацию.
{@value}, когда использующийся в статическом полевом комментарии, возвращает его значение. Этот тег полезен для вставки значения в комментарий документа. Это изменение потребовало добавления к API Doclet методы FieldDoc.constantValue() и FieldDoc.constantValueExpression() в пакете com.sun.javadoc. ()
Добавленный -noqualifier опция, чтобы опустить квалифицировать имя пакета от перед именами классов в выводе
Предыдущее поведение было следующие: На странице для класса p. C добавьте, что пакет называет только к классам, не принадлежащим пакету p. Параметр -noqualifier любой"all"(все спецификаторы пакета опускаются), или отдельный от двоеточия список пакетов, с подстановочными знаками, чтобы быть удаленным как спецификаторы (такие как "Java lang:java.awt:javax. *").
Добавьте ссылки к исходному коду, используя -linksource опция
Создает версию HTML каждого исходного файла и добавляет ссылки им из нормальной документации. (Именованный -src в Бете 2. Переименует это к -linksource в окончательной версии, чтобы лучше дифференцировать это от -source.) ()
Помещенный текущий класс или пакет называют сначала в заголовке окна.
Это позволяет имени появиться в панели задач Windows, когда окно минимизируется. (Также работы в Internet Explorer, когда фреймы включаются.)
Генерируйте страницу пакета, передавая в исходных именах файлов (*.java). Документы, которые сгенерированы, не должны несколько отличаться, передавая на имена пакета, передавая в исходных именах файлов для классов в тех пакетах.
Поместите ссылку класса исключений в раздел бросков в двух случаях:
(1) там a @throws тег, но никакой текст сопровождает тег
(2) если исключение объявляется, но нет никакого тега
Добавленный -nocomment подавить описание и теги, генерируя только объявления. Включения, снова использующие исходные файлы первоначально, предназначаются в различной цели.
Ошибочный статус выхода - Фиксированный javadoc, чтобы использовать статус выхода doclet.
Используйте - кодирование опции, читая package.html.
Добавленный "Все Классы" панели навигации для улучшенной доступности
Файлы документа каталога теперь копируются, передавая в.java файлах - передавая в исходных файлах (*.java) к Javadoc, он теперь копирует каталоги "файлов документа" в место назначения. (Прежде, каталоги "файлов документа" не были скопированы.) Это поведение теперь идентично этому, передавая на имена пакета.
Фиксированный каталог файлов документа в документе базируется, чтобы быть скопированным в место назначения.
Это позволяет включению документации на уровне краткого обзора быть включенным.
Добавленный -docfilessubdirs чтобы включить глубокой копии файлов документа - Подкаталоги каталога "файлов документа" теперь рекурсивно копируются в место назначения когда -docfilessubdirs используется. Например, doc-files/example/images и все его содержание было бы теперь скопировано. Если Вы нуждаетесь в этом, эта опция также доступна: -excludedocfilessubdir name1>:<name2>... исключить любые подкаталоги файлов документа с именами. Это предотвращает копирование SCCS и других подкаталогов управления исходным кодом. Ранее, только файлы непосредственно в "файлах документа" были скопированы.
Фиксированный {@docroot} во фрейме HTML - {@docroot} тег теперь должным образом разрешается, когда это появляется в верхнем левом фрейме HTML (overview-frame.html). ()
Фиксированный {@docroot} в @see - {@docroot} тег теперь должным образом разрешается, когда это появляется в тексте @see тег.
Фиксированный {@link} с {@docRoot} - {@docRoot} тегируйте больше не отключает никого {@link} тег, который следует за этим в том же самом комментарии.
Заголовок "Реализаций" - комментарий документа, наследованный от абстрактного метода теперь, использует надлежащий подзаголовок "реализации", а не "переопределения".
Фиксированный "Класс с реализацией" на интерфейсной странице - Исправленная ошибка на интерфейсной странице, где некоторые классы не обнаруживались как "класс с реализацией".
Фиксированный дисплей статических инициализаторов - инициализатор static {...} вызванный "Методы, Наследованные От" таблицы, чтобы запуститься с запятой (). Базовая ошибка была этим javadoc, который рассматривают static {} быть анонимным методом. Это больше не будет появляться как запись метода в сгенерированных документах.
Должным образом поля документа и методы для частных внутренних классов.
Исправленные "вложенные классы" терминология - Javadoc теперь используют термин "вложенные классы", а не "внутренние классы" всюду по его заголовкам и подзаголовкам. Определения: "Вложенный класс является любым классом, объявление которого происходит в пределах тела другого класса или интерфейса." в то время как "Внутренний класс является вложенным классом, который не статичен." Поэтому, "вложенный" более общий термин.
API Doclet больше не сериализуем. - Классы больше не расширяются сериализуемый. (Было бы невозможно, вообще, должным образом сериализировать их.) Представьте имя файла и номер строки объявлений. Новый класс SourcePosition был добавлен к API Doclet, так же как новому методу position() в Doc и Tag (см. 4192783). Они включают полному разложению и реконструкции исходных файлов. (, 4208989)
Добавленный MethodDoc.overriddenMethod() для того, чтобы возвратить список методов, которые переопределяются.
Улучшенная документация API Doclet.
Потенциальная несовместимость - Tag у интерфейса теперь есть a position() метод. Doclets, которые реализуют 1.3 Tag интерфейс (такой как MIF Doclet 1.2 Беты 1) не будет работать с Javadoc 1.4.
configuration параметр MessageRetriever подпись конструктора. Это может влиять на код, который разделяет стандарт на подклассы doclet. Новый конструктор теперь MessageRetriever(Configuration configuration, String resourcelocation) (Никакое число ошибки)
Полная перереализация инструмента Javadoc и API (4400430): - Javadoc теперь использует новый javac компилятор вместо старого.
Известны несколько изменений в поведении. Они не ошибки и никогда не будут, вероятно, "фиксироваться" в javadoc:
<clinit>. Новый javadoc правильно опускает их.this$0 параметр конструкторам для вложенных классов. В то время как это соглашается с отражающим представлением этих конструкторов, это не корректно из источника или точки зрения языка. Новый javadoc сообщает о подписи, как это появляется в источнике.this$0 как сериализуемое поле. Новый javadoc правильно опускает упоминание о this$0 и другие синтетические элементы. См. java.util.logging.LogManager.LogProperties для примера.java.io.PipedOutputStream есть (бесполезно и избыточно)"import java.io.*;". Новый javadoc правильно включает это в список импорта.java.util.regex.Pattern.Caret. Обходное решение должно использовать локаль, которая поддерживает более широкий набор Unicode.Некоторые далее известные примеры неправильного поведения старого javadoc преднамеренно воспроизводятся в новой javadoc реализации для совместимости. Например, если класс a. Внутренних классов и Вы импортируете их использование:
import a.A.*;
Старый Javadoc неправильно сообщил бы (через API Doclet) об импорте:
import a.*;
Нет никакого способа корректного выражения этого объявления импорта с током javadoc API. Экземпляры ClassDoc больше не уникальны - До 1.4.0, каждый задокументированный класс был представлен единственным экземпляром ClassDoc - это было недокументированной деталью реализации. С 1.4.0, это больше не истина - инструмент Javadoc способен к созданию двух различных экземпляров ClassDoc, которые представляют тот же самый класс. Это повредило бы любой doclets, который по ошибке полагался на этот факт. Одна такая ошибка была : - опция использования строго повреждается.
