hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [Httpcomponents Wiki] Update of "JavaDocGuidelines" by RolandWeber
Date Sun, 27 Jan 2008 19:14:20 GMT
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


Mime
View raw message