[digester] @author and @version

[Simon Kitching <si...@ecnetwork.co.nz>]

Hi All,

I've just got stuck into removing the @author tags as agreed earlier (we
can discuss about adding @author "Jakarta team" or similar later).

But what should we do about the @version tag?
This is present on about 50% of files.

Is it needed? What purpose does it serve? What do other commons projects
do wrt this tag?

If we can agree that it is in or out, I can make that change at the same
time as the @author change (remove it from all files or add it to all
files).

Regards,

Simon


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

Re: [digester] @author and @version

[Stephen Colebourne <sc...@btopenworld.com>]

Two common forms are

@version $Id: $
@version $Revision: $ $Date: $

Stephen

----- Original Message ----- 
From: "Simon Kitching" <si...@ecnetwork.co.nz>
> Hi All,
> 
> I've just got stuck into removing the @author tags as agreed earlier (we
> can discuss about adding @author "Jakarta team" or similar later).
> 
> But what should we do about the @version tag?
> This is present on about 50% of files.
> 
> Is it needed? What purpose does it serve? What do other commons projects
> do wrt this tag?
> 
> If we can agree that it is in or out, I can make that change at the same
> time as the @author change (remove it from all files or add it to all
> files).
> 
> Regards,
> 
> Simon
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org


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

Re: [digester] @author and @version

[Stephen Colebourne <sc...@btopenworld.com>]

I would personally prefer to see the @version tag remain holding this info.
Its where it is in most other projects, its near the top of the file and
fairly non-intrusive. If you don't want it in the javadoc simply exclude
it - in ant version="false" on javadoc task.

Stephen

----- Original Message -----
From: "Simon Kitching" <si...@ecnetwork.co.nz>
> Ok, here's a solution I hope will satisfy everyone. Can people please
> give their opinion on this?
>
> There seemed to be general agreement that having this info as @version
> in the javadoc is not useful, but having it somewhere in the text for
> developers to refer to is.
>
> So I propose that the following is added as the *last* line of every
> digester .java file:
>
> // version: $Id$
>
> This makes it really easy to find, without being intrusive for people
> studying the code. And "tail -n 1 *.java" will dump the version info for
> every file in the local dir, which seems useful. [and it will be really
> easy to automate the process to add the version info :-].



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

Re: [digester] @author and @version

[Simon Kitching <si...@ecnetwork.co.nz>]

On Fri, 2004-04-09 at 23:11, robert burrell donkin wrote:
> On 9 Apr 2004, at 02:10, Craig McClanahan wrote:
> 
> > matthew.hawthorne wrote:
> >
> >> Simon Kitching wrote:
> >>
> >>> What benefit is there in having this info in the source?
> >>> I can't currently see any:
> >>>  * Developers can just use "cvs status".
> >>>  * End users just care that the file came from "version 2.1".
> >>>  * Maybe it is useful info when working with source snapshots,    
> >>> but that isn't very common.
> >>>
> >>> What am I missing?
> >>
> >>
> >> I think it's a convenience to be able to see when the last change was 
> >> made, and who made it, in the source file -- instead of doing  'cvs 
> >> status'.  But that's about it.
> > I like having the "$Id$" string somewhere at the top of each file, 
> > because I often download the sources onto my laptop, and can't execute 
> > "cvs status" from an airplane.
> 
> +1
> 
> the version doesn't add anything (but distractions ;) to the javadocs 
> but having an $Id$ tag somewhere is useful (on occasion).
> 
> i think that henri's right about good @since tags being much more 
> useful. if this was done just before each release, it'd probably be 
> possible to use a script to add these to every method and every class 
> (which does not have them already).

Ok, here's a solution I hope will satisfy everyone. Can people please
give their opinion on this?

There seemed to be general agreement that having this info as @version
in the javadoc is not useful, but having it somewhere in the text for
developers to refer to is.

So I propose that the following is added as the *last* line of every
digester .java file:

// version: $Id$

This makes it really easy to find, without being intrusive for people
studying the code. And "tail -n 1 *.java" will dump the version info for
every file in the local dir, which seems useful. [and it will be really
easy to automate the process to add the version info :-].

The major drawback I see is that no other project does it this way (that
I know of). But someone's got to be first, right?

Alternatively, the same line could be inserted between the class javadoc
and the class declaration. This places the info in about the same place
it was with the @version javadoc approach. 



Unfortunately when this info is added to the file, it will of course be
the same for every single file, just showing the date the "// version"
change was made, plus the user who did it. Any suggestions for working
around this?

Regards,

Simon


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

Re: [digester] @author and @version

[robert burrell donkin <ro...@blueyonder.co.uk>]

On 9 Apr 2004, at 02:10, Craig McClanahan wrote:

> matthew.hawthorne wrote:
>
>> Simon Kitching wrote:
>>
>>> What benefit is there in having this info in the source?
>>> I can't currently see any:
>>>  * Developers can just use "cvs status".
>>>  * End users just care that the file came from "version 2.1".
>>>  * Maybe it is useful info when working with source snapshots,    
>>> but that isn't very common.
>>>
>>> What am I missing?
>>
>>
>> I think it's a convenience to be able to see when the last change was 
>> made, and who made it, in the source file -- instead of doing  'cvs 
>> status'.  But that's about it.
> I like having the "$Id$" string somewhere at the top of each file, 
> because I often download the sources onto my laptop, and can't execute 
> "cvs status" from an airplane.

+1

the version doesn't add anything (but distractions ;) to the javadocs 
but having an $Id$ tag somewhere is useful (on occasion).

i think that henri's right about good @since tags being much more 
useful. if this was done just before each release, it'd probably be 
possible to use a script to add these to every method and every class 
(which does not have them already).

- robert


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

Re: [digester] @author and @version

[Craig McClanahan <cr...@apache.org>]

matthew.hawthorne wrote:

> Simon Kitching wrote:
>
>> What benefit is there in having this info in the source?
>> I can't currently see any:
>>  * Developers can just use "cvs status".
>>  * End users just care that the file came from "version 2.1".
>>  * Maybe it is useful info when working with source snapshots,    but 
>> that isn't very common.
>>
>> What am I missing?
>
>
> I think it's a convenience to be able to see when the last change was 
> made, and who made it, in the source file -- instead of doing  'cvs 
> status'.  But that's about it.
>
I like having the "$Id$" string somewhere at the top of each file, 
because I often download the sources onto my laptop, and can't execute 
"cvs status" from an airplane.

> However, with the recent craze over @author tags, maybe we shouldn't 
> even be using $Id$ anymore, since it contains the committer's username.
>
The committer's username isn't going to be hidden even without $Id$, 
because "cvs log" will show it.  But that's a totally separate thing 
from what @author is/was about.

Craig


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

Re: [digester] @author and @version

["matthew.hawthorne" <ma...@apache.org>]

Simon Kitching wrote:
> What benefit is there in having this info in the source?
> I can't currently see any:
>  * Developers can just use "cvs status".
>  * End users just care that the file came from "version 2.1".
>  * Maybe it is useful info when working with source snapshots, 
>    but that isn't very common.
> 
> What am I missing?

I think it's a convenience to be able to see when the last change was 
made, and who made it, in the source file -- instead of doing  'cvs 
status'.  But that's about it.

However, with the recent craze over @author tags, maybe we shouldn't 
even be using $Id$ anymore, since it contains the committer's username.

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

Re: [digester] @author and @version

[Simon Kitching <si...@ecnetwork.co.nz>]

On Thu, 2004-04-08 at 10:31, Simon Kitching wrote:
> Hi All,
> 
> I've just got stuck into removing the @author tags as agreed earlier (we
> can discuss about adding @author "Jakarta team" or similar later).
> 
> But what should we do about the @version tag?
> This is present on about 50% of files.
> 
> Is it needed? What purpose does it serve? What do other commons projects
> do wrt this tag?
> 
> If we can agree that it is in or out, I can make that change at the same
> time as the @author change (remove it from all files or add it to all
> files).

Oh - one thought. If we're going to move to subversion sometime, then
subversion doesn't have a concept of file version numbers. 

It does have the concept of "a repository version", which increments
with every commit to the repository. You can say "the version of the
file which was in repository version #86509" but not "the third commit
of this file".

On Thu, 2004-04-08 at 10:47, Stephen Colebourne wrote: 
> Two common forms are
> 
> @version $Id: $
> @version $Revision: $ $Date: $

So I gather you do use this in collections at least? 

What benefit is there in having this info in the source?
I can't currently see any:
 * Developers can just use "cvs status".
 * End users just care that the file came from "version 2.1".
 * Maybe it is useful info when working with source snapshots, 
   but that isn't very common.

What am I missing?

Cheers, Simon


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