Развернуть встроенные теги в пользовательском теглете Javadoc

Я написал собственный тег Javadoc, который добавляет новый тег 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.

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

Спасибо!


java javadoc custom-tag taglet
person Mark    schedule 16.11.2010    source источник

Ответы (2)


arrow_upward
2
arrow_downward

В обзоре теглета говорится:

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

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

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

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

person Paŭlo Ebermann    schedule 25.02.2011

arrow_upward
1
arrow_downward

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

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

  2. Вы можете использовать tag.holder().setRawCommentText(String). Мой опыт игры с этим заключается в том, что это позволяет вам добавлять теги, но не позволяет вам переписывать тег. Таким образом, вы не можете выполнить замену строки в tag.holder().getRawCommentText(), а затем заставить стандартный доклет правильно отображать встроенные теги, но вы, вероятно, могли бы использовать свой метод 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).

person Jeremy    schedule 13.03.2011