Расширить встроенные теги в пользовательском джавадоке.

Question

Я написал пользовательский джавадок тарлет, который добавляет новый note ярлык:

 ...
 public boolean isInlineTag() { return false; }

  public String toString(Tag tag) {
      return "<pre class='note'>" + tag.text() + "</pre>";
   }

Это работает до сих пор, но встроенные теги не расширяются. Вот пример комментария:

/**
 * @note Test note with {@link Someclass} // @link tag is NOT expanded
 * @param name - here the {@link Someclass} works // works for standard 'param' tag
 */

А {@link} Встроенный тег не расширяется. Тем не менее, это отлично работает для встроенного param Javadoc Tag.

Есть ли способ расширить вложенные встроенные теги в пользовательском Taglet Javadoc?

Спасибо!

Answer 1

А Обзор тагалета говорит:

Томары могут быть записаны в виде блочных тегов, таких как @todo, или встроенные теги, такие как {@underline}. Блок Тагалетов в настоящее время не поддерживают встроенные теги в своем тексте.

На самом деле, API Taglet слишком минимален, так как он поддерживает только toString() метод

Внутри этого метода вы можете получить подтэги параметра tag (с .inlineTags()), но тогда вам придется отформатировать их самостоятельно, так как у вас нет доступа к обычному механизму стандартного доктора из вашего тага.

Итак, похоже, вам здесь не повезло, если вы не хотите переопределить (или копировать) части стандартного доктора в своем собственном тагале. (Но тогда вы можете точно напрямую расширить стандартный доклет вместо исправления его с помощью тагал.)

Answer 2

Вот три возможных идеи, ни одна из которых мне действительно нравится:

1. Вместо определения собственного Taglet, использовать -tag вариант на javadoc командование для поддержки @note. Анкет Конечно, это не позволит вам определить собственное пользовательское форматирование.

2. Вы могли бы использовать tag.holder().setRawCommentText(String). Анкет Мой опыт игры с этим заключается в том, что это позволяет добавлять теги, но не позволяет вам переписать тег. Так что вы не можете сделать замену строки на tag.holder().getRawCommentText() а затем сделать стандартный Docle Taglet.toString(Tag[]) Метод генерировать HTML, включая необработанную форму встроенных тегов, а затем добавить к необработанному тексту комментария »@renderedNote markedup Tag.text ()" куда @renderedNote это еще один тег, определяемый с помощью -tag. Анкет Ваш Taglet.toString(Tag[]) затем вернуть пустую строку. Тем не менее, это не только уродливое, я не знаю, опирается ли это на недокументированное поведение, и поэтому я не знаю, насколько надежными или будущими доказательствами эта идея.

3. Вы могли бы иметь свой Taglet также реализовать com.sun.tools.doclets.internal.toolkit.taglets.Taglet. Анкет Похоже, это так, как определяются стандартные тагальи. Два метода, которые вам нужно реализовать, - это TagletOutput getTagletOutput(Tag tag, TagletWriter writer) а также TagletOutput getTagletOutput(Doc doc, TagletWriter writer). Анкет Я думаю, последнее может просто throw IllegalArgumentException(). Анкет Если вы также сохраните Map при условии, когда ваш Taglet был зарегистрирован, тогда вы сможете представить несколько встроенных тегов, с которыми вы сталкиваетесь, посмотрев имя тега в этом Map Чтобы получить его реализацию com.sun.tools.doclets.internal.toolkit.taglets.Taglet и делегировать его getTagletOutput метод Однако, например, похоже, например, @link Теги не зарегистрированы на этой карте; Для них это возможно (но я не проверил) это, потому что @link теги предположительно предоставляются как SeeTag Вы можете использовать карту из @see Вместо этого, или вы можете разыграть TagletWriter к TagletWriterImpl а затем используйте TagletWriterImpl.seeTagOutput(Doc, SeeTag[]). Анкет За Text теги, вы можете генерировать TagletOutput экземпляры через new TagletOutputImpl(String). Анкет Наконец все TagletOutput Случаи, которые вы получите таким образом, могут быть объединены в один TagletOutput быть возвращенным с помощью TagletOutput.append(TagletOutput).