[cp-patches] Usage of the @see tags

[Meskauskas Audrius]

> The @see tag should be used inline in the javadocs instead of the
> <code>somemethod()</code> constructs, as discussed privately.
>
>
> Michael
What exactly do you mean?

The @see tag is not used inline. All @see tags must be grouped under the 
heading, same as @para, @author, @return and others. The @link and 
@linkplain tags can be used inline, but as you suggested @see, I have used 
@see - this also looked acceptable.  If I use @see, I must leave <code> as 
otherwise the comment is difficult to read. The reader needs to think if 
this is a part of the sentence or java identifier.

I do not know, maybe some documentation generators are error tolerant, 
treating @see as @link after they find it in a wrong place. However this 
seems clearly an error and I will not correct it.

Regards
Audrius

P.S. This is from my documentation:
@see  reference
Adds a "See Also" heading with a link or text entry that points to 
reference. A doc comment may contain any number of @see tags, which are all 
grouped under the same heading. (...)  For inserting an in-line link within 
a sentence to a package, class or member, see address@hidden