[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[cp-patches] Re: Usage of the @see tags
From: |
Michael Koch |
Subject: |
[cp-patches] Re: Usage of the @see tags |
Date: |
Fri, 25 Feb 2005 22:34:13 +0100 |
User-agent: |
mutt-ng 1.5.8i (Debian) |
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.