JavaMethod#getComment() is parsed with an implicit order

Here is a small sample:

    /**
     * A Javadoc sample.
     *
     * @return The size.
     */
    public long getSize()
    {
        return 0;
    }

    /**
     * @return The size.
     *
     * A Javadoc sample.
     */
    public long getSize2()
    {
        return 0;
    }

The javaMethod.getComment() is empty for getSize2() and should be equal to "A Javadoc sample."
If it is a known limitation, the API should reflect this limitation.

I attached a test case which displays the following.

Looking the class: test.TestQDOX154
Looking the method: getSize
javaMethod.getComment()=A Javadoc sample.
javaMethod.getTagByName( "return" )=The size.
Looking the method: getSize2
javaMethod.getComment()=
javaMethod.getTagByName( "return" )=The size.

A Javadoc sample.

test added, but succeeds right now. Good chance it's already solved by another issue (rev. 611)

test was invalid, issue needs another review

qdox-168 will contain a new parsing stategy for javadoc comments which should make this issue easier to solve

I've been thinking: what to do if there's a description above AND below a tag? Only one place to find the answer:http://java.sun.com/j2se/javadoc/writingdoccomments/#format
According to this, the current behaviour is correct.
But some data will get lost this way. So I'm not yet sure what to do. An option could be to add an extra method which will return the complete block unparsed.
But I don't really like this, so maybe we should consider this as a "won't resolve".

Robert, according the doc, my understanding is the same than you: the behaviour is correct.
I propose that you add some documentation with this pointer and close this issue as you proposed.

For the record, here is the javadoc tool test:

    /**
     * @return The size.
     *
     * A Javadoc sample.
     */
    public long getSize2()
    {
        return 0;
    }

Here is the generated Javadoc by the Javadoc tool:

<a name="getSize2()"><!-- --></a><h3>
getSize2</h3>
<pre>public long <b>getSize2</b>()</pre>
<dl>
<dd><dl>
</dl>
</dd>

<dd><dl>

<dt><b>Returns:</b></dt><dd>The size.

 A Javadoc sample.</dd></dl>
</dd>
</dl>

Closing issue because behaviour follows javadoc specs. I added the test with proper expecting values to prefend other behaviour in the future.