Как создать пользовательские теги Javadoc? - PullRequest
Новая
       7

Как создать пользовательские теги Javadoc?

26 голосов
/ 20 апреля 2010

Как мне создать пользовательские теги Javadoc, такие как @pre / @post? Я нашел несколько ссылок, которые объясняют это, но мне не повезло с ними. Вот некоторые из ссылок:

http://www.developer.com/java/other/article.php/3085991/Javadoc-Programming.html

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html

Ответы [ 4 ]

25 голосов
/ 15 сентября 2011

код Java 

/**
 * @custom.mytag hey ho...
 */

опция Java-документа 

-tag custom.mytag:a:"This is my Tag:"

выход

Это мой тэг:

эй хо ...

13 голосов
/ 22 октября 2012

Пользовательские теги не должны создаваться с использованием HTML, потому что javadoc может изменить его реализацию или способ представления данных, возможно, они начнут использовать Markdown в будущем, также экспортер Javadoc не будет перехватывать недостающую информацию и у вас могут быть пустые теги.

Сначала используйте любой желаемый тег: 

/**
 * Comments and a {@link #methodLink} for this method.
 * 
 * @tt.wrapper {@link OtherClass}
 *
 */
public String extractName() {
    // method contents
}

Обратите внимание, что пользовательский тег имеет формат @[prefix].[tagName], это связано с тем, что doclet (или другой плагин Eclipse) может выпустить свой собственный тег с тем же именем, и ваш тег просто переопределит стандартный тег, поэтому мы добавляем префикс, чтобы уменьшить вероятность этого.

Комментарий от доклета.

Пользовательские теги, которые могут переопределять будущие стандартные теги: @wrapper Чтобы избежать возможных переопределений, используйте как минимум один символ точки (.) В именах пользовательских тегов.

Теперь вы должны сообщить экспортеру Javadoc об этом пользовательском теге @tt.wrapper. Перейдите на Project > Generate Javadoc.. в Затмении (Индиго в моем случае).

После настройки параметров для первых двух экранов этого диалогового окна (используя «Далее» для изменения экранов) вы должны увидеть этот экран:

Third configuration screen for Eclipse Doclet Javadoc Export

Вы должны заметить, что текстовое поле «Дополнительные параметры Javadoc ..» имеет значение, которое вы должны добавить для экспортера Javadoc для создания HTML-эквивалента вашего тега.

В нашем случае вариант такой (если вам нужно несколько тегов, поместите их в новую строку): 

-tag tt.wrapper:a:"API Wrapper:"

Теперь, когда вы экспортируете свой Javadoc (я также рекомендую сохранить сценарий ANT , чтобы вам не приходилось каждый раз проходить через это диалоговое окно), ваш пользовательский тег будет выделен жирным шрифтом с описанием, значения внизу.

P.S. Мне еще предстоит найти способ добавить возможность добавления автозаполнения для пользовательских тегов, но в Indigo это кажется невозможным, возможно, это произойдет в будущих выпусках (не уверен, что у Juno есть).

0 голосов
/ 11 марта 2017

Если вы хотите несколько, сделайте что-то вроде javadoc -tag pre -tag post -tag invariant, где он запрашивает аргументы командной строки. Не используйте html материал

0 голосов
/ 20 апреля 2010

Ну, то, что я сделал, не лучшее решение, но читабельное: 

  /** <p><b>Pre:</b></p>  <Ul>True</Ul>
    * <p><b>Post:</b></p> <Ul>The x is pushed onto the top of the stack,
    *                       and the rest of the stack remains unchanged.</Ul>
    *
    * @param x              Indicates the current node
    */
   public void push(int x){
      ...
   }

Пока правильный ответ не найден, надеюсь, он поможет!

...