You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geronimo.apache.org by David Jencks <da...@yahoo.com> on 2009/09/09 20:01:53 UTC
javadoc @version tags
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.
thanks
david jencks
Re: javadoc @version tags
Posted by "Alan D. Cabrera" <ad...@toolazydogs.com>.
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
Re: javadoc @version tags
Posted by David Jencks <da...@yahoo.com>.
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.
thanks
david jencks
>
>
> Regards,
> Alan
>
Re: javadoc @version tags
Posted by "Alan D. Cabrera" <ad...@toolazydogs.com>.
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.
Regards,
Alan