[cp-patches] Re: Usage of the @see tags

[Michael Koch]

On Fri, Feb 25, 2005 at 10:22:45PM +0100, Meskauskas Audrius wrote:
> >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 

This happens when you just believe when you see others doing this. You
are right. I exchange @see and @link. Please replace @see in my former
mails with @link. Sorry again.

We use @see in some instances inlined in some sentences. We should really
fix this.


Michael


P.S.L Please wrap your mails at a line width of around 74. Makes it much
easier for me to read the mails on small displays in textmode. No
scrollin needed.