james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Noel J. Bergman" <n...@devtech.com>
Subject RE: Javadoc @version, @since and CVS $Id$
Date Tue, 17 Jun 2003 21:58:25 GMT
> as an old user of SourceSafe I'm used to share files among projects,
> and I'm surprised to infer from your words that it is not a common
> practice (or even not possible) to do it in the CVS world. Is it true?

CVS cannot share files as SourceSafe does.  Each branch has its own copy.  I
really liked SourceSafe when it was a One Tree Software product, and
multi-platform, but I can't fault Brian & Company for selling out,
considering what they got.

One more reason for Subversion, which I believe supports sharing.

> > Sun's convention is to use the SCCS version

> > So the header could be:
> >   @version [CVS] $Id$
> >   @since <release version>

> Better then:

>  <P>CVS $Id$</P>
>  @version CVS $Revision$
>  @since <release version>

$Revision$ is part of $Id$.  As far as I'm concerned, it is a sufficient
part, but that's not my personal call.  I'm not sure if $Name$ will give you
what you want.  Danny or Serge might know.

> two different .java files patched in the same moment for the same reason
may have two
> totally unrelated $Revision$ numbers. And I would like to see a reference
to a shared
> milestone of the project

That's not the purpose of the @version tag.  The purpose of the @version tag
is to identify the code.  You might want to get a copy of cvs2cl, which can
produce nice change logs, and provide a good overview of related changes.

> I see a relationship between @version and @since

> http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/javadoc.html#@version
> it contradicts the link above from this point of view

Actually, not.  If you go to the bottom of the section you referenced, they
say "For more details, see writing @version tags", where they go on to
elaborate that "The Java Software convention for the argument to the
@version tag is the SCCS string."  Using @version as:

  <P>CVS $Id$</P>
  @version 3.0
  @since 2.2.3

doesn't use the javadoc @version tag to hold the critical version

@since <release> is important to let outside developers know which version
of the released product introduced the interface.  @version is important to
cross-reference a problem back into the source code control system.

> And also notice that @since (and not @version) can be coded for a method

Correct.  @since tells you when something in the interface was introduced.
@version tells you what version of that file you are looking at, so that you
can match it up against the source control system.

	--- Noel

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

View raw message