Javadoc Jsdoc writing something after @param and @return contents blocks?

Question

Do you know if it's possible to write something after the @param and @return blocks. Let's say I want to write a piece of text after the parameters/return declarations, something that is separated from them.

It seems Javadoc and Jsdoc both attach whatever you write after an @param/@return in the same block of conetnts.

Let's say for instance I want documentation to be shown like this:

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

Short answer, No you can't do that.

Long answer, JavaDoc is designed such that a comment has two sections, the narraitve free form section, and the block section. Once you start using any of the block tags, they are only delimited by the next block tag. There is not a tag to 'end' the block section, so whatever the final tag you use, the text up to the end of the comment will be associated with it. That said, there is also a well established convention for the usage of JavaDoc tags, including the ordering of the information. (see http://java.sun.com/j2se/javadoc/writingdoccomments/).

The closest that I believe you will be able to come to what you are attempting, is to use the @see tag to link to an html file with the notes in it.

Answer 2

What you are trying to do can't be done due to the format of JavaDoc comments. JavaDoc does allow some HTML though so I have gotten around this previously by adding my own "notes" areas.

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