Javadoc Jsdoc 在 @param 和 @return 内容块之后写一些东西？

Question

你知道是否可以在@param和@return块之后写一些东西。 假设我想在参数/返回声明之后编写一段文本，与它们分开。

看来 Javadoc 和 Jsdoc 都将您在 @param/@return 之后编写的任何内容附加到同一内容块中。

比方说，我希望文档显示如下：

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 的设计使得注释有两个部分：叙述自由形式部分和块部分。一旦开始使用任何块标签，它们仅由下一个块标签分隔。没有用于“结束”块部分的标记，因此无论您使用什么最终标记，直到注释末尾​​的文本都将与其关联。
也就是说，JavaDoc 标签的使用也有一个完善的约定，包括信息的排序。 （请参阅http://java.sun.com/j2se/javadoc/writingdoccomments/）。

我相信您能够实现您正在尝试的最接近的方法是使用 @see 标记链接到其中包含注释的 html 文件。