Как процитировать "* /" в JavaDocs - PullRequest
Новая
       9

Как процитировать "* /" в JavaDocs

44 голосов
/ 10 марта 2009

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

Пример: 

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

Follow : Похоже, я могу использовать / для слэша. Единственным недостатком является то, что это не все, что читается при просмотре кода непосредственно в текстовом редакторе. 

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

Ответы [ 6 ]

36 голосов
/ 10 марта 2009

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

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

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

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

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

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

Edit:

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

Так что? Дело не в том, чтобы ваш код был читабельным, а в том, чтобы ваш код документация была читабельной. Большинство комментариев 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)
8 голосов
/ 11 июля 2014

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

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

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

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

7 голосов
/ 11 марта 2009 
/**
 * Returns true if the specified string contains "*/".
 */

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

/**
 * Returns true if the string contains an asterisk followed by slash.
 */
6 голосов
/ 10 марта 2009

Использовать сущность 

*/

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

5 голосов
/ 10 марта 2009

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

// */ is html for */
4 голосов
/ 10 марта 2009

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

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

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

...