commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [ALL] @version tag :)
Date Tue, 05 Apr 2011 14:34:31 GMT
On Tue, Apr 5, 2011 at 10:27 AM, Paul Benedict <pbenedict@apache.org> wrote:

> The only benefit of the @version tag is that it shows up in javadoc. The
> $Id$, if at the top of the file, does not. It's nice to see the subversion
> number in API documents. I prefer that since it lets me track down the
> actual version in a repository.
>

+1 to Id at the top.

Are we coming to a consensus to be documented?

Gary

>
> Paul
>
> On Tue, Apr 5, 2011 at 8:58 AM, Gary Gregory <garydgregory@gmail.com>
> wrote:
>
> > On Tue, Apr 5, 2011 at 6:19 AM, sebb <sebbaz@gmail.com> wrote:
> >
> > > On 5 April 2011 10:44, sebb <sebbaz@gmail.com> wrote:
> > > > On 5 April 2011 09:55, Simone Tripodi <simonetripodi@apache.org>
> > wrote:
> > > >> Hi all guys!
> > > >>
> > > >> @Torsten: I agree, question is that I have never understood why the
> > > >> common usage is putting SVN tags in @version javadoc, so since I
> > > >> noticed a mixed usage, I wondered which one is the commonly used;
> > > >>
> > > >> @Christian: I intended @version, because existing source have *a
> lot*
> > > >> of that tag; for @since instead the common usage seems to be correct
> > > >>
> > > >> BTW I would be +1 for NO @version and putting only @since
> > > >
> > > > I think the intention of the @version tag is to identify code that is
> > > > not stored in SVN - e.g. in a source archive.
> > > >
> > > > $Revision$ and $Id$ (or even $HeadUrl) are fine in @version comments,
> > > > however please don't use $Date$ as that is expressed in local time.
> > > > This really messes up release checking as the dates in source
> archives
> > > > don't match the dates in SVN tag checkouts unless the same timezone
> is
> > > > being used.
> > >
> > > In case it's not obvious, I am
> > >
> > > -1 to banning @version, as it can be useful
> > >
> >
> > Since $Id$ contains the user ID we I would an @version that contains the
> > revision number. I find that useful. I like to see a revision number in
> the
> > manifest too (if it's not there already), like
> >
> >
> http://maven.apache.org/plugin-developers/cookbook/add-svn-revision-to-manifest.html
> >
> > Gary
> >
> >
> > > +1 to banning $Date$ in @version
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> >
> >
> > --
> > Thank you,
> > Gary
> >
> > http://garygregory.wordpress.com/
> > http://garygregory.com/
> > http://people.apache.org/~ggregory/
> > http://twitter.com/GaryGregory
> >
>



-- 
Thank you,
Gary

http://garygregory.wordpress.com/
http://garygregory.com/
http://people.apache.org/~ggregory/
http://twitter.com/GaryGregory

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message