geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Alan D. Cabrera" <...@toolazydogs.com>
Subject Re: javadoc @version tags
Date Thu, 10 Sep 2009 21:05:28 GMT

On Sep 9, 2009, at 3:31 PM, David Jencks wrote:

>
> On Sep 9, 2009, at 1:14 PM, Alan D. Cabrera wrote:
>
>>
>> On Sep 9, 2009, at 11:01 AM, David Jencks wrote:
>>
>>> I was looking at the generated xbean site prior to releasing and  
>>> noticed the version looks pretty messy with lots of random  
>>> variations.  I think we've previously encouraged something like  
>>> this:
>>>
>>>  * @version $Rev:$ $Date:$
>>>
>>> which expands to something like
>>>
>>>  * @version $Rev: 437551 $ $Date: 2006-08-27 23:14:47 -0700 (Sun,  
>>> 27 Aug 2006) $
>>>
>>> which ends up in javadoc as something like
>>>
>>> Version:
>>> $Rev$ $Date$
>>> or
>>>
>>> Version:
>>> $Rev: 437551 $ $Date: 2006-08-27 23:14:47 -0700 (Sun, 27 Aug 2006) $
>>>
>>> This seems wrong to me.  I think in javadoc the version ought to  
>>> be something like 3.6-SNAPSHOT or 3.6.
>>>
>>> So, I'd like to propose that:
>>>
>>> 1. we investigate and find out if there's a way to set the javadoc  
>>> version to the maven version.  If so, use it.  If not, remove the  
>>> @version.
>>>
>>> 2. Decide if we want the svn keyword info in the java files at  
>>> all, and if so get it out from the @version javadoc tag.
>>
>> What do other projects do?  It's always been my understanding that  
>> the @version relates to the version of the code file and not the  
>> release.
>
> So far the documentation I've found (http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#

> @version) says:
>
> The Java Software convention for the argument to the @version tag is  
> the SCCS string "%I%, %G%", which converts to something like "1.39,  
> 02/28/97" (mm/dd/yy) when the file is checked out of SCCS.
>
> Also (http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html# 
> @version),
>
> @version  version-text
> Adds a "Version" subheading with the specified version-text to the  
> generated docs when the -version option is used. This tag is  
> intended to hold the current version number of the software that  
> this code is part of (as opposed to @since, which holds the version  
> number where this code was introduced). The version-text has no  
> special internal structure. To see where the version tag can be  
> used, see Where Tags Can Be Used.
> A doc comment may contain multiple @version tags. If it makes sense,  
> you can specify one version number per @version tag or multiple  
> version numbers per tag. In the former case, the Javadoc tool  
> inserts a comma (,) and space between names. In the latter case, the  
> entire text is simply copied to the generated document without being  
> parsed. Therefore, you can use multiple names per line if you want a  
> localized name separator other than comma.
>
>
> While the meaning of "1.39" is not clear, it might be a cvs version  
> number, which is sort of analogous to an svn revision number.  On  
> the other hand, the second snippet indicates that it is analogous to  
> the @since tag and that the versions specified in both should be  
> comparable: this would agree with the idea that the maven version  
> number is more appropriate.

It seems that either would be fine.  I think, like you, that the  
latter would be more useful to users reading the documentation.


Regards,
Alan


Mime
View raw message