Имеет ли Javadoc эквивалент <! [CDATA [...]]>?

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

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

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

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

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

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

Ответ 1

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

Ответ 2

Расширение @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.

Ответ 3

Закройте и снова откройте тег {@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>

Ответ 4

Я пробовал довольно много решений, ни одна из которых не была очень удовлетворительной для моих нужд. Обычно выполняются теги 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-escaping (вы можете использовать этот, чтобы заставить его правильно отображать

Это:

 &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. К счастью, затмение может сделать это для вас на лету...