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文件。

Javadoc Jsdoc在@param和@return内容块之后写了些什么？

2 个答案: