代码之家 › 专栏 › 技术社区 › Marco Demaio

javadoc jsdoc在@param和@return contents块后面写东西?

jsdoc javadoc

0

Marco Demaio · 技术社区 · 15 年前

你知道在@param和@return块之后是否可以写一些东西吗? 假设我想在参数/返回声明之后写一段文本,就是 分离的 从他们那里。

似乎javadoc和jsdoc都在同一个conetnts块中返回@param/@之后附加了您编写的任何内容。

例如,我希望文档显示如下:

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.

2 回复 | 直到 15 年前

1

0

JiroDan 15 年前

简短的回答,不,你不能这样做。

答案很长,JavaDoc的设计使得一个注释有两个部分,narraivefreeform部分和block部分。一旦开始使用任何块标记,它们就只能由下一个块标记分隔。没有用于“结束”块节的标记,因此无论您使用的最终标记是什么,注释末尾的文本都将与之关联。也就是说,对于javadoc标签的使用,包括信息的排序,也有一个很好的惯例。(见 http://java.sun.com/j2se/javadoc/writingdoccomments/ )

我认为你能做到的最接近的一点是,使用@see标记链接到一个包含注释的HTML文件。

2

1

brainimus user417509 15 年前

由于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
 */