Как заключать в кавычки */ в JavaDocs

Мне нужно включить */ в комментарий JavaDoc. Проблема в том, что это та же самая последовательность для закрытия комментария. Как правильно процитировать/избежать этого?

Пример:

/**
 * Returns true if the specified string contains "*/".
 */
public boolean containsSpecialSequence(String str)

Дополнение. Кажется, я могу использовать / для косой черты. Единственным недостатком является то, что это не так уж читабельно при просмотре кода непосредственно в текстовом редакторе.

/**
 * Returns true if the specified string contains "*/".
 */

java comments javadoc
person Steve Kuo    schedule 10.03.2009    source источник
comment
Мне нравится предложение bobince включать звездочку, за которой следует косая черта, возможно, в круглых скобках после литерала */. Затем его можно прочитать как в коде, так и в Javadoc.   -  person ide    schedule 15.11.2010

Ответы (6)


arrow_upward
42
arrow_downward

Используйте экранирование HTML.

Итак, в вашем примере:

/**
 * Returns true if the specified string contains "*/".
 */
public boolean containsSpecialSequence(String str)

/ экранируется как символ "/".

Javadoc должен беспрепятственно вставлять экранированную последовательность в генерируемый им HTML, и это должно отображаться в вашем браузере как "*/".

Если вы хотите быть очень осторожным, вы можете экранировать оба символа: */ переводится как */.

Изменить:

Дополнение. Кажется, я могу использовать / вместо косой черты. Единственным недостатком является то, что это не так читабельно при непосредственном просмотре кода.

Так? Дело не в том, чтобы ваш код был удобочитаемым, дело в том, чтобы ваш код документация был удобочитаемым. Большинство комментариев Javadoc содержат сложный HTML для объяснения. Черт, эквивалент C# предлагает полную библиотеку тегов XML. Я видел там довольно замысловатые конструкции, скажу я вам.

Редактировать 2: Если это вас слишком беспокоит, вы можете встроить встроенный комментарий, не относящийся к javadoc, который объясняет кодировку:

/**
 * Returns true if the specified string contains "*/".
 */
// returns true if the specified string contains "*/"
public boolean containsSpecialSequence(String str)
person Randolpho    schedule 10.03.2009
comment
Я бы пошел на Б. - person Tom Hawtin - tackline; 10.03.2009
comment
Это кого-то еще беспокоит, кроме меня? Теперь это выглядит хорошо в javadoc, но нечитаемо, когда вы просто смотрите на исходный код... - person Outlaw Programmer; 10.03.2009
comment
Это не совсем нечитабельно. Ты программист, да? По крайней мере, вы должны быть в состоянии понять, что это escape-код HTML, даже если вы не узнаете фактическое значение. Вы всегда можете посмотреть его. Как я уже говорил, смысл javadoc — в удобочитаемости документации, а не в коде. - person Randolpho; 10.03.2009
comment
Тем не менее, вы всегда можете вставить комментарий, который не является Javadoc, чтобы объяснить это себе в другом месте вашего кода. Что-то вроде: // ищет */ - person Randolpho; 10.03.2009
comment
Просто откройте представление javadoc в вашей среде IDE. Они, как правило, довольно крутые в эти дни... - person Stephen; 10.03.2009
comment
Одно замечание, которое можно упомянуть, заключается в том, что это не будет экранировано в блоках {@code }, и если требуется код или предварительно отформатированный вывод, он должен существовать в блоке <code></code> вместо этого. - person Brett Ryan; 12.08.2016

arrow_upward
13
arrow_downward

Никто не упомянул {@literal}. Это еще один способ:

/**
 * Returns true if the specified string contains "*{@literal /}".
 */

К сожалению, вы не можете избежать */ одновременно. С некоторыми недостатками это также исправляет:

Единственным недостатком является то, что это не так уж читабельно при просмотре кода непосредственно в текстовом редакторе.

person Lyubomyr Shaydariv    schedule 11.07.2014

arrow_upward
9
arrow_downward 

/**
 * Returns true if the specified string contains "*&#47;".
 */

Это «правильное» решение, но для удобочитаемости я бы, вероятно, выбрал:

/**
 * Returns true if the string contains an asterisk followed by slash.
 */
person bobince    schedule 10.03.2009
comment
хорошо, хорошо, но этот совет не очень полезен, когда вы приводите примеры шаблонов оболочки, например. foo/bar/**/baz.zip - person Jason S; 17.10.2019

arrow_upward
6
arrow_downward

Используйте сущность

*&#47;

В вашей документации он будет отображаться как "*/"

person cpatrick    schedule 10.03.2009

arrow_upward
6
arrow_downward

Еще один способ, на который я наткнулся, просто для полноты картины: добавить HTML-разметку, которая не изменяет вывод между * и /.

  /**
   * *<b/>/
   */

По сравнению с решением для выхода из HTML это кажется уродливым хаком, но он также дает правильный результат в выводе HTML.

person Jonik    schedule 10.03.2009
comment
Не совсем; ваше предложение в его нынешнем виде, скорее всего, нарушит html-документы. Если бы кто-то пошел по этому пути, я бы предложил что-то вроде: ‹b›*‹/b›‹b›/‹/b›, чтобы убедиться, что теги закрыты. - person Randolpho; 10.03.2009
comment
Ах, я думал об этом, но оставил так, потому что это самый короткий вариант, и он отлично работал в IDEA (Ctrl-Q). Если не ‹b/›, не будет ли достаточно *‹b›‹/b›/ или *‹span/›/? - person Jonik; 10.03.2009

arrow_upward
6
arrow_downward

Я бы посоветовал вам также добавить строчный комментарий где-то рядом с чем-то вроде

// *&#47; is html for */
person hasen    schedule 10.03.2009