Разверните встроенные теги в пользовательском теге Javadoc - PullRequest
Новая
       61

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

4 голосов
/ 16 ноября 2010

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

<code> ...
 public boolean isInlineTag() { return false; }

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

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

/**
 * @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?

Спасибо!

Ответы [ 2 ]

2 голосов
/ 25 февраля 2011

Обзор тегов говорит:

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

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

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

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

1 голос
/ 13 марта 2011

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

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

  2. Вы можете использовать tag.holder().setRawCommentText(String).Мой опыт игры с этим заключается в том, что это позволяет вам добавлять теги, но не позволяет переписывать теги.Таким образом, вы не можете выполнить замену строки в tag.holder().getRawCommentText(), и тогда стандартный доклет правильно отобразит встроенные теги, но, возможно, ваш Taglet.toString(Tag[]) метод сгенерирует html, включая необработанную форму встроенных тегов, а затемдобавить к необработанному тексту комментария "@renderedNote markUp 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).

...