Есть ли в Javadoc эквивалент ‹![CDATA[ ]]›?

К сожалению, в HTML нет CDATA.

Жаль, потому что это было бы идеально для добавления javadoc комментариев, включающих XML, поэтому вам не нужно экранировать символы ‹ и >, например:

/**<![CDATA[ This parses <complexType name=""> ]]>*/

Однако javadoc может распознать раздел CDATA и преобразовать его в HTML для вас. Например:

This parses &lt;complexType name=""&gt;

Или он может использовать более простой синтаксис, чем CDATA. Поскольку javadoc является расширяемым, возможно, кто-то добавил эту функциональность; а может javadoc уже где-то внутри зарыл... Кто-нибудь знает?


java xml html javadoc cdata
person 13ren    schedule 23.11.2009    source источник

Ответы (4)


arrow_upward
46
arrow_downward

Вы можете использовать тег @code JavaDoc: /** This parses {@code <complexType name="">} */

person Fabian Steeg    schedule 23.11.2009
comment
+1 Обратите внимание, что {@code ... } может занимать несколько строк. eclipse будет утверждать, что это ошибка, но это не так. Он также выполняет подсчет фигурных скобок! Таким образом, вы можете использовать фигурки в своем фактическом фрагменте кода, если они совпадают. - person Kevin Bourrillion; 23.11.2009
comment
Я вижу, как IDEA обрабатывает многострочный блок {@code}, складывая строки вместе, чего не будет с <pre>. Это грустно, так как {@code} звучало как хорошее решение, чтобы не убегать от открывающих кареток. - person seh; 13.01.2011

arrow_upward
33
arrow_downward

Расширяя @Fabian answer, я использую как <pre>, так и {@code ...}. Вот пример с XML в качестве исходного кода:

/*Outputs data from a result set to an XML
 * with following structure:
 * <pre>
 * {@code
 * <row>
 *  <FIELD1>gregh</FIELD1>
 *  <FIELD2>487</FIELD2>
 *  <!-- etc. -->
 * </row>
 * <!-- more rows-->
 * }
 * </pre>
 */

<pre> позволяет писать код в несколько строк и сохранять его структуру.

Протестировано с Eclipse 3.6.1.

person bluish    schedule 28.12.2011

arrow_upward
8
arrow_downward

Закройте и снова откройте тег {@code} вокруг фигурных скобок, чтобы ${dollar_sign_variables} правильно отображались в eclipse, несмотря на ошибка 206319 и ошибка 206345 и не прибегая к полное экранирование HTML:

/*
 * <pre>
 * {@code
 * <outer>
 *   <inner1>Text</inner1>
 *   <inner2>$}{ "script" }{@code </inner2>
 * </outer>
 * }
 * </pre>
 */

который отображается в Eclipse Indigo SR2 (3.7.2) как

<outer>
  <inner1>Text</inner1>
  <inner2>${ "script" }</inner2>
</outer>
person willkil    schedule 26.09.2012

arrow_upward
3
arrow_downward

Я пробовал довольно много решений, ни одно из которых не удовлетворяло мои потребности. Выполнение тегов pre + @code (или @literal) обычно работает:

 <pre>
 {@literal
 <configFiles>
   <configFile>
     <type>LOGICAL_INDEX_CONFIG</type>
   </configFile>
 </configFiles>}
 </pre>

Проблема в том, что если у вас есть ${dollar_sign_variables} в вашем html? (и это часто, если в вашей документации используются примеры xml, основанные на фильтрации maven). Скажем, у вас есть ${ITEM_INDEX_TO_LOGICAL}, Eclipse отобразит его следующим образом:

<configFiles>
  <configFile>
     ITEM_INDEX_TO_LOGICAL

   }

В конечном счете, у меня не было выбора, кроме как придерживаться метода экранирования html (вы можете использовать этот), чтобы он правильно отображался:

Этот:

 &lt;configFiles&gt;
   &lt;configFile&gt;
     &lt;type&gt;${ITEM_INDEX_TO_LOGICAL}&lt;/type&gt;
   &lt;/configFile&gt;
 &lt;/configFiles&gt;

Рендерит вот так:

 </configFiles>
   <configFile>
     <type>${ITEM_INDEX_TO_LOGICAL}</type>
   </configFile>
 </configFiles>

Это, к сожалению, поставит вас в положение, когда вы не сможете по-настоящему понять документированный «пример xml», если не отобразите Javadoc. К счастью, eclipse может сделать это за вас на лету...

person Choppy The Lumberjack    schedule 06.06.2012