Javadoc Jsdoc что-то пишет после блоков содержимого @param и @return?

Question

Знаете ли вы, можно ли что-то написать после блоков @param и @return.Допустим, я хочу написать фрагмент текста после объявлений параметров / возврата, что-то, что отделено от них.

Кажется, Javadoc и Jsdoc оба прикрепляют все, что вы пишете после @param/ @ вернуть в том же блоке conetnts.

Скажем, например, я хочу, чтобы документация отображалась так:

function showUpperCaseString(string_to_show)
This function shows the input string in upper case and blah, blah, ...

Parameters:

   {string} string_to_show

Returns:

   {boolean} true if everything was ok, or false on failure

   It's important to notice that I would like to show this text NOT in the
   return contents. But the Javadoc, Jsdoc always attach everything to the last
   @param/@return block. Even if I use nexline <br> or <p> it goes new line but 
   still indented as if it was part of the last return block.

Answer 1

То, что вы пытаетесь сделать, невозможно сделать из-за формата комментариев JavaDoc. JavaDoc действительно допускает некоторый HTML, поэтому я обошел это ранее, добавив свои собственные области заметок.

/**
 * Brief summary of what the method does here.
 * 
 * <p>
 * <b> NOTE: An IllegalStateException will be thrown if 
 * the object has not been initialized. </b>
 * </p>
 * 
 * <p>
 * <b> NOTE: Some additional information here about when
 * an <code>IllegalStateException</code> is thrown. </b>
 * </p>
 * 
 * @param aUseDefaults
 *            information about the parameter goes here
 * 
 * @throws IllegalStateException
 *            when the object isn't in the correct state
 */

Answer 2

Короткий ответ, Нет, ты не можешь этого сделать.

Длинный ответ, JavaDoc разработан таким образом, что комментарий имеет два раздела: раздел свободной формы narraitve и раздел блоков. Как только вы начинаете использовать любой из тегов блока, они ограничиваются только следующим тегом блока. Нет тега для «окончания» секции блока, поэтому с любым последним тегом, который вы используете, будет связан текст до конца комментария. Тем не менее, существует также хорошо установленное соглашение об использовании тегов JavaDoc, в том числе упорядочение информации. (см. http://java.sun.com/j2se/javadoc/writingdoccomments/).

Самое близкое, на что, я думаю, вы сможете прийти к тому, что вы пытаетесь, - это использовать тег @see для ссылки на html-файл с примечаниями.