Как избежать использования фигурных скобок во встроенных тегах javadoc, таких как тег {@code}

Question

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: {@code <custom:meatball color="<%= Meatball.RED %> nincompoop="${person}" />}
 * 
 * @author King Cong
 * 
 */

Часть "$ {person}" ломает комментарий к документу, поскольку использует фигурные скобки.

Answer 1

Не столько ответ, сколько обходной путь, но если вы замените {@code ...} на старую версию <code>..., вы получите фигурные скобки, как вы ожидаете.

<code>{person} == ${person}</code>

К сожалению, это разбивает угловые скобки, поэтому на исходный вопрос вам нужно уйти от этих:

<code>&lt;custom:meatball color="&lt;%= Meatball.RED %&gt; nincompoop="${person}" /&gt;</code>

Вы даже можете обмануть здесь, заставив Notepad ++ сделать это за вас, с помощью удобного TextFX -> convert -> Encode HTML (& <> ").

Это, по крайней мере, имеет то преимущество, что все хорошо воспроизводится как в сгенерированном Javadoc, так и в Eclipse в представлении Javadoc, которое, кажется, не понимает } и друзей.

Answer 2

Попробуйте использовать экранирование HTML:

${person} == ${person}

Answer 3

решение bodunbodun работает, как это обычно бывает, что у вас есть новая строка также в Javadocs. Экранирование HTML не будет работать, если вы хотите и {, и новую строку

<code><pre>
{@code
<foo bar="}${bar}{@code"/>
<bar foo="}${foo}{@code"/>
}

даст вам

<foo bar="${bar}" />
<bar foo="${foo}" />

Answer 4

У меня была такая же проблема на самом деле - ни одно из предложений не сработало для меня (переходы HTML не работают по любой причине). Если это поможет - попробуйте закрыть {@code} перед проблемным символом и открыть его после, например:

{@ code nincompoop = "} $ {person} {@ code " />}

Это не кажется решением, но оно работает и не нарушает форматирование, если использовать его осторожно:)

Answer 5

По крайней мере, в Java 1.8.0_31 я больше не могу воспроизвести проблему. Ваш ввод отображается как и ожидалось:

<code>&lt;custom:meatball color="&lt;%= Meatball.RED %&gt; nincompoop="${person}" /&gt;</code>

Мои тесты показывают, что javadoc учитывает сбалансированные фигурные скобки внутри @code и заканчивает его только тогда, когда найдена соответствующая фигурная скобка.

Так что, если код имеет сбалансированные фигурные скобки {}, как в вашем примере, теперь он работает как положено.

Но я до сих пор не знаю, что делать с несбалансированными фигурными скобками, такими как:

{@code printf"}<b>outside</b>"}

Кроме того, поведение зависит от того, какой встроенный тег вы используете. man javadoc прямо говорит, что для @link:

If you need to use the right brace (}) inside the label, then use the HTML entity notation }.

Так что в этом случае невозможно сделать что-то лучше.

К сожалению, я не смог найти похожую цитату для @code, которая подкрепляет мои эксперименты.

Answer 6

Найден другой не звездный обходной путь для этого. Это лучше или хуже, чем другие? Я позволю тебе решить. Возьмите часть {@code } и замените ее на <code> . (Это заставляет все это исчезнуть из-за угловых скобок.) Возьмите самую первую < и оберните ее в {@literal }, чтобы она выглядела так {@literal<} Теперь все будет хорошо, и это не слишком ужасно в коде. Конечный результат выглядит так

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: <code>{@literal<}custom:meatball color="<%= Meatball.RED %> nincompoop="${person}" /></code>
 * 
 * @author King Cong
 * 
 */

В качестве альтернативы, если вам не нравится {@literal<}, вы можете вместо этого использовать <. Результат будет выглядеть так:

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: <code> &lt;custom:meatball color="<%= Meatball.RED %> nincompoop="${person}" /></code>
 * 
 * @author King Cong
 * 
 */

Не являются отличными решениями, но они работают.

Answer 7

Используйте {@literal}, поэтому сделайте это {@literal } }. Работает в моих тестах.

Так что для вашего случая это будет выглядеть так:

/**
 * Gets the meatball icon for a nincompoop.
 * 
 * <p>
 * Example: {@code <custom:meatball color="<%= Meatball.RED %> nincompoop="${person{@literal } }" />}
 * 
 * @author King Cong
 * 
 */