[prev in list] [next in list] [prev in thread] [next in thread] 

List:       httpclient-commons-dev
Subject:    Re: [Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
From:       sebb <sebbaz () gmail ! com>
Date:       2008-01-27 19:14:20
Message-ID: 25aac9fc0801271114t7b3a07ebke82d2e5ccc66196a () mail ! gmail ! com
[Download RAW message or body]

On 27/01/2008, Roland Weber <ossfwot@dubioso.net> wrote:
> sebb wrote:
> > For Java 1.5 and up, one can use Annotations such as:
> >
> > @ThreadSafe
> > @NotThreadSafe
> > @GuardedBy
> > @Immutable
> >
> > Perhaps it would be a good idea to start including these where possible?
>
> Makes sense, though I believe these are not JavaDocs?
> I have to read up on this stuff one of these days.
> (so much to do on that "one of these days"...)
>

Yes, sorry - I should have made it clear that this is a follow-on from
the details in the Wiki.

It looks like at least some of the annotations appear in the Javadoc -
e.g. ThreadSafe does.

> > For 1.4 and earlier, maybe they could be included as comments?
> >
> > The @GuardedBy annotation is potentially very useful.
>
> I don't mind making the JavaDocs more useful, if that is
> what you mean with "as comments". I wouldn't see a point in
> comments only visible in the source, like /*@ThreadSafe*/.
>

Well, the annotations are more useful if they appear in Javadoc, but
they still have use in comments. E.g. @GuardedBy would be useful to
developers, and even ThreadSafe would be useful as a reminder not to
compromise the code.

As soon as the code needs 1.5, the comment markers could be removed.

> cheers,
>   Roland
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org

[prev in list] [next in list] [prev in thread] [next in thread]