commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Simon Kitching <si...@ecnetwork.co.nz>
Subject Re: [digester] @author and @version
Date Sat, 17 Apr 2004 11:47:56 GMT
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


Mime
View raw message