Spec-Zone .ru
спецификации, руководства, описания, API
Содержание документации

Краткий обзор Taglet

Содержание

API Taglet

Taglets являются программами, записанными в языке программирования Java™, которые реализуют API Taglet. Taglets может быть записан как любой метки блока, такой как @todo, или встроенные теги, такой как {@underline}. Блок taglets в настоящий момент не поддерживает встроенные теги в их тексте. (См. блок и встройте теги.) API Taglet состоит из одного интерфейса: taglet может изменить и отформатировать текстовый параметр пользовательского тега, и сделать другие вещи, такие как перенаправление текст к файлу или другому потоку. taglet может переопределить стандартный тег.

Taglets являются основой ниже -tag опция. Когда Вы используете -tag опция, это использует встроенный taglet, чтобы генерировать HTML значения по умолчанию, форматирующий, который подобен сгенерированному для @return.

Запись Taglet

Вот основные шаги, за которыми Вы должны следовать, чтобы создать и использовать Ваш собственный taglet:

  1. Запишите программу Java, которая составляет Ваш taglet. Ваша программа должна импортировать следующее:
       import com.sun.tools.doclets.Taglet;    // Taglet API
       import com.sun.javadoc.*;               // Doclet API
       import java.util.Map;                   // Used in register(Map)
    
    com.sun.javadoc классы должны быть импортированы для Tag интерфейс, используемый в toString(Tag).
  2. Ваш class должен реализовать требования интерфейса, который он расширяет. toString метод - то, где вся пользовательская работа реализуется, чтобы изменить, отформатировать или перенаправить текстовый параметр, который передают в к Вашему пользовательскому тегу.
        public String toString(Tag tag)
    
  3. В дополнение к требованиям интерфейса Вы реализуете, Ваша программа должна реализовать следующий статический метод. Затем позволяет taglet быть загруженным во времени выполнения. См. исходный код в примере ниже.
        public static void register(Map tagletMap)  
    
    
  4. Скомпилируйте свой doclet. Используйте javac версию 1.4.0 компилятора (или позже) в JDK. Необходимые файлы class находятся в lib\tools.jar файл в JDK. Для первого примера ниже, принимая JDK устанавливается в C:\Program Files\j2sdk1.4.1.
       javac -classpath "C:\Program Files\j2sdk1.4.1\lib\tools.jar"  ToDoTaglet.java
    
  5. Выполните javadoc инструмент, используя -taglet и -tagletpath опции. Например, если Ваш taglet файл class определяется, чтобы быть в пакете com.sun и сохранен в C:\taglets\com\sun\Taglet.class, тогда следует установить tagletpath в C:\taglets. Этот пример вызовы javadoc на пакете com.package1, включая ToDoTaglet теги:
       javadoc -taglet ToDoTaglet -tagletpath C:\taglets com.package1
    

Следующие примеры имеют блок и встраивают taglets.

Пример - Блок Taglet

Исходный код для примера блока taglet реализация @todo включается в: Соответствующий файл class ToDoTaglet.class уже компилируется и сохраняется в том же самом каталоге как этот исходный файл.

Этот taglet форматирует вывод для @todo тег. Комментарий документа, содержащий следующий тег:

    /**
     * @todo Fix this!
     */
тогда ToDo taglet форматирует вывод HTML следующим образом:
Сделать:
Фиксируйте это!

Описание реализации

Давайте смотреть на исходный код. Чтобы назвать тег и определить текст заголовка, определите два частных поля:
    private static final String NAME = "todo";
    private static final String HEADER = "To Do:";
Чтобы сделать это меткой блока, а не встроенным тегом, Вы устанавливаете isInlineTag возвращать false:
    public boolean isInlineTag() {
        return false;
    }
Есть другие методы inField, inMethod, inType, inPackage и inOverview то, что Вы определяете true или false указать, в которых комментариях документа в исходном коде может использоваться этот тег.

toString(Tag) метод определяет, как текст вставляется в вывод когда сингл {@todo} с тегом встречаются. Этот код создает полужирный заголовок, сопровождаемый таблицей с желтым фоном, который содержит текст (определенный tag.text()).

    public String toString(Tag tag) {`
        return "<DT><B>" + HEADER + "</B><DD>"
               + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
               + tag.text() 
               + "</td></tr></table></DD>\n";
    }
Точно так же toString(Tag[]) метод (который берет массив тегов) определяет, как текст вставляется в вывод когда кратное число {@todo} с тегами встречаются.

Метод регистра

    /**
     * Register this Taglet.
     * @param tagletMap  the map to register this tag to.
     */
    public static void register(Map tagletMap) {
       ToDoTaglet tag = new ToDoTaglet();
       Taglet t = (Taglet) tagletMap.get(tag.getName());
       if (t != null) {
           tagletMap.remove(tag.getName());
       }
       tagletMap.put(tag.getName(), tag);
    }

Пример - Встроенный Taglet

В отличие от меток блока, пользовательский встроенный тег может только быть реализован, используя taglet (вместо того, чтобы использовать -tag опция). Это - то, потому что нет никакого поведения значения по умолчанию для встроенных тегов.

Исходный код для примера встроенной реализации taglet {@underline} включается в:

Соответствующий файл class UnderlineTaglet.class уже компилируется и сохраняется в том же самом каталоге как этот исходный файл.

Этот taglet форматирует вывод для {@underline} тег. Комментарий документа, содержащий следующий тег:

    /**
     * Be sure to insert the value at the {@underline start} of the array.
     */
был бы выведен в HTML следующим образом:

Убедитесь, что вставили значение в начале массива.

Описание реализации

Давайте смотреть на то, как этот исходный код отличается от предыдущего примера. Конечно, имя тега отличается (и у встроенных тегов нет никакого заголовка, таким образом, ни один не определяется):
    private String NAME = "underline";
Чтобы определить это как встроенный тег, а не метку блока, Вы устанавливаете isInlineTag возвращать true:
    public boolean isInlineTag() {
        return true;
    }

Методы inField, inMethod, inConstructor, inType, inPackage и inOverview применяйтесь только к меткам блока, и должен все быть установлен в ложь для встроенных тегов.

toString(Tag) метод определяет, как текст вставляется в вывод когда {@underline} с тегом встречаются. Этот код создает, окружает текст тегами подчеркивания HTML <ul> и </ul>.

    public String toString(Tag tag) {
        return "<u>" + tag.text() + "</u>";
    }
Не возможно иметь массив встроенных тегов, чтобы обработать, как это с метками блока. Поэтому, toString(Tag[]) метод (который берет массив тегов) игнорируется для встроенных тегов.

Ошибки из-за неправильного обращения и Предупреждения

Ошибки - taglet может сообщить об ошибке и остановить инструмент Javadoc, просто печатая сообщение об ошибке и затем вызов System.exit().

Предупреждения - taglet может сообщить о предупреждении, используя MessageRetriever, данный этому экземпляром Doclet. MessageRetriever получается из объекта Конфигурации. Объект Конфигурации получается из doclet. Например, если Taglet разрабатывается, чтобы использоваться со Стандартом doclet, Конфигурация может быть получена, используя Standard.configuration(), статический метод. Как пример, это то, как SimpleTaglet предупреждения печатных изданий, который является значением по умолчанию taglet для -tag опция.


Oracle и/или его филиалы Авторское право © 1993, 2012, Oracle и/или его филиалы. Все права защищены.
Свяжитесь с Нами