0

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

似乎 Javadoc 和 Jsdoc 都将您在 @param/@return 之后编写的任何内容附加到同一块 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.
4

2 回答 2

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
 */
于 2010-06-21T17:30:13.323 回答
0

简短的回答，不，你不能那样做。

长答案，JavaDoc 的设计使得评论有两个部分，叙述自由形式部分和块部分。一旦您开始使用任何块标记，它们仅由下一个块标记分隔。没有标签可以“结束”块部分，因此无论您使用最终标签，直到注释末尾​​的文本都将与之相关联。也就是说，JavaDoc 标记的使用也有一个完善的约定，包括信息的排序。（见http://java.sun.com/j2se/javadoc/writingdoccomments/）。

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

于 2010-06-21T17:17:33.687 回答