You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Konstantin Kolinko <kn...@gmail.com> on 2009/07/07 02:01:20 UTC
[PROPOSAL] Remove SVN keywords from JavaDoc
As was written early in this my thread:
http://www.nabble.com/Coding-Guidelines%2C-encodings%2C-keywords-td23662661.html
(http://markmail.org/thread/d6dsgrsfvnuzclt7)
there are problems with Subversion $Date$ keyword:
1. It uses localized names for the month and the day of the week
2. It writes those localized strings using UTF-8, while our sources
are ISO-8859-1
3. The time that is printed is in local timezone
There are two possible solutions (besides ignoring the issue):
a) Use $Id:$ keyword instead
b) Remove the keyword
For the java sources, I propose the simpler one of the above:
I propose to remove *all* SVN keywords from our *.java sources, where they are
used in JavaDoc comments.
That includes the following four keywords: Author Date Id Revision
As it is a documentation change, I won't propose a patch, but go C-T-R.
What are your opinions?
If there are any objections to such a change, please write so.
I think that having SVN keywords in JavaDoc is not so useful, because
- Classes do change often, but their JavaDoc do not so.
- You know, to what TC release your JavaDoc corresponds to. Why to need more?
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: [PROPOSAL] Remove SVN keywords from JavaDoc
Posted by sebb <se...@gmail.com>.
On 07/07/2009, Mark Thomas <ma...@apache.org> wrote:
> Konstantin Kolinko wrote:
> > As was written early in this my thread:
> > http://www.nabble.com/Coding-Guidelines%2C-encodings%2C-keywords-td23662661.html
> > (http://markmail.org/thread/d6dsgrsfvnuzclt7)
> >
> > there are problems with Subversion $Date$ keyword:
> > 1. It uses localized names for the month and the day of the week
> > 2. It writes those localized strings using UTF-8, while our sources
> > are ISO-8859-1
> > 3. The time that is printed is in local timezone
> >
> > There are two possible solutions (besides ignoring the issue):
> > a) Use $Id:$ keyword instead
> > b) Remove the keyword
> >
> > For the java sources, I propose the simpler one of the above:
> >
> > I propose to remove *all* SVN keywords from our *.java sources, where they are
> > used in JavaDoc comments.
> > That includes the following four keywords: Author Date Id Revision
> >
> > As it is a documentation change, I won't propose a patch, but go C-T-R.
> >
> > What are your opinions?
> > If there are any objections to such a change, please write so.
>
>
> I'm happy getting rid of all of them. The only times I have used them
> there have been equally quick, equally effective ways of finding out the
> information I was after (usually Tomcat version).
+1
Apart from encoding issues, any SVN keywords that can vary between
users (e.g. Header, Date) are a nuisance when comparing source files
(e.g. tag checkout against source archive) as they generate spurious
differences.
> Mark
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
> For additional commands, e-mail: dev-help@tomcat.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: [PROPOSAL] Remove SVN keywords from JavaDoc
Posted by Mark Thomas <ma...@apache.org>.
Konstantin Kolinko wrote:
> As was written early in this my thread:
> http://www.nabble.com/Coding-Guidelines%2C-encodings%2C-keywords-td23662661.html
> (http://markmail.org/thread/d6dsgrsfvnuzclt7)
>
> there are problems with Subversion $Date$ keyword:
> 1. It uses localized names for the month and the day of the week
> 2. It writes those localized strings using UTF-8, while our sources
> are ISO-8859-1
> 3. The time that is printed is in local timezone
>
> There are two possible solutions (besides ignoring the issue):
> a) Use $Id:$ keyword instead
> b) Remove the keyword
>
> For the java sources, I propose the simpler one of the above:
>
> I propose to remove *all* SVN keywords from our *.java sources, where they are
> used in JavaDoc comments.
> That includes the following four keywords: Author Date Id Revision
>
> As it is a documentation change, I won't propose a patch, but go C-T-R.
>
> What are your opinions?
> If there are any objections to such a change, please write so.
I'm happy getting rid of all of them. The only times I have used them
there have been equally quick, equally effective ways of finding out the
information I was after (usually Tomcat version).
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: [PROPOSAL] Remove SVN keywords from JavaDoc
Posted by Rainer Jung <ra...@kippdata.de>.
On 07.07.2009 04:34, William A. Rowe, Jr. wrote:
> Rainer Jung wrote:
>> So I like the idea of using Id, but I am open to arguments for dropping it.
>
> In httpd, we use; <!-- $LastChangedRevision: 654723 $ --> in the reference
> file, and the tag <!-- English Revision: 421100:654723 (outdated) --> which
> is updated in order to determine how far out of sync translations have fallen.
>
> So there is one argument for at least one embedded svn property.
Konstantin: you might not know that part of httpd development. The
procedure Bill describes is for tracking out of date translated
documentation pages. So it is not directly related to the auto-generated
javadocs. It could be used e.g. for the message resource files to
detect, for which languages they haven't been updated.
I never checked how that procedure is actually implemented. I suspect it
used some ant or xsl facilities and not only svn builtins, so it might
not be easy to apply to the LocalStrings properties files.
Regards,
Rainer
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: [PROPOSAL] Remove SVN keywords from JavaDoc
Posted by "William A. Rowe, Jr." <wr...@rowe-clan.net>.
Rainer Jung wrote:
>
> So I like the idea of using Id, but I am open to arguments for dropping it.
In httpd, we use; <!-- $LastChangedRevision: 654723 $ --> in the reference
file, and the tag <!-- English Revision: 421100:654723 (outdated) --> which
is updated in order to determine how far out of sync translations have fallen.
So there is one argument for at least one embedded svn property.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: [PROPOSAL] Remove SVN keywords from JavaDoc
Posted by Rainer Jung <ra...@kippdata.de>.
On 07.07.2009 02:01, Konstantin Kolinko wrote:
> As was written early in this my thread:
> http://www.nabble.com/Coding-Guidelines%2C-encodings%2C-keywords-td23662661.html
> (http://markmail.org/thread/d6dsgrsfvnuzclt7)
>
> there are problems with Subversion $Date$ keyword:
> 1. It uses localized names for the month and the day of the week
> 2. It writes those localized strings using UTF-8, while our sources
> are ISO-8859-1
> 3. The time that is printed is in local timezone
>
> There are two possible solutions (besides ignoring the issue):
> a) Use $Id:$ keyword instead
> b) Remove the keyword
>
> For the java sources, I propose the simpler one of the above:
>
> I propose to remove *all* SVN keywords from our *.java sources, where they are
> used in JavaDoc comments.
> That includes the following four keywords: Author Date Id Revision
>
> As it is a documentation change, I won't propose a patch, but go C-T-R.
>
> What are your opinions?
> If there are any objections to such a change, please write so.
>
>
> I think that having SVN keywords in JavaDoc is not so useful, because
> - Classes do change often, but their JavaDoc do not so.
> - You know, to what TC release your JavaDoc corresponds to. Why to need more?
I had a look at the java folder in trunk. The following files contain
SVN keywords outside of javadoc but inside comments (it seems they only
use $Id):
Java-Files:
javax/servlet/AsyncContext.java
javax/servlet/AsyncEvent.java
javax/servlet/AsyncListener.java
javax/servlet/DispatcherType.java
javax/servlet/FilterRegistration.java
javax/servlet/Registration.java
javax/servlet/ServletContainerInitializer.java
javax/servlet/ServletRegistration.java
javax/servlet/SessionCookieConfig.java
javax/servlet/SessionTrackingMode.java
javax/servlet/annotation/HandlesTypes.java
javax/servlet/annotation/MultipartConfig.java
javax/servlet/annotation/WebFilter.java
javax/servlet/annotation/WebInitParam.java
javax/servlet/annotation/WebListener.java
javax/servlet/annotation/WebServlet.java
org/apache/catalina/startup/ConnectorCreateRule.java
org/apache/catalina/startup/SetNextNamingRule.java
org/apache/tomcat/util/digester/AbstractObjectCreationFactory.java
org/apache/tomcat/util/digester/AbstractRulesImpl.java
org/apache/tomcat/util/digester/ArrayStack.java
org/apache/tomcat/util/digester/CallMethodRule.java
org/apache/tomcat/util/digester/CallParamRule.java
org/apache/tomcat/util/digester/Digester.java
org/apache/tomcat/util/digester/FactoryCreateRule.java
org/apache/tomcat/util/digester/GenericParser.java
org/apache/tomcat/util/digester/NodeCreateRule.java
org/apache/tomcat/util/digester/ObjectCreateRule.java
org/apache/tomcat/util/digester/ObjectCreationFactory.java
org/apache/tomcat/util/digester/ObjectParamRule.java
org/apache/tomcat/util/digester/ParserFeatureSetterFactory.java
org/apache/tomcat/util/digester/PathCallParamRule.java
org/apache/tomcat/util/digester/Rule.java
org/apache/tomcat/util/digester/RuleSet.java
org/apache/tomcat/util/digester/RuleSetBase.java
org/apache/tomcat/util/digester/Rules.java
org/apache/tomcat/util/digester/RulesBase.java
org/apache/tomcat/util/digester/SetNextRule.java
org/apache/tomcat/util/digester/SetPropertiesRule.java
org/apache/tomcat/util/digester/SetPropertyRule.java
org/apache/tomcat/util/digester/SetRootRule.java
org/apache/tomcat/util/digester/SetTopRule.java
org/apache/tomcat/util/digester/WithDefaultsRulesWrapper.java
org/apache/tomcat/util/digester/XercesParser.java
org/apache/tomcat/util/net/SSLSessionManager.java
LocalStrings.properties:
javax/servlet/http/LocalStrings_es.properties
org/apache/catalina/realm/LocalStrings.properties
org/apache/catalina/realm/LocalStrings_es.properties
org/apache/catalina/realm/LocalStrings_fr.properties
org/apache/catalina/realm/LocalStrings_ja.properties
org/apache/coyote/ajp/LocalStrings.properties
org/apache/coyote/http11/LocalStrings.properties
org/apache/coyote/http11/LocalStrings_es.properties
org/apache/coyote/http11/LocalStrings_fr.properties
org/apache/coyote/http11/LocalStrings_ja.properties
org/apache/jasper/resources/LocalStrings.properties
org/apache/jasper/resources/LocalStrings_es.properties
org/apache/jasper/resources/LocalStrings_fr.properties
org/apache/jasper/resources/LocalStrings_ja.properties
org/apache/naming/LocalStrings_es.properties
Others
javax/servlet/resources/XMLSchema.dtd
javax/servlet/resources/datatypes.dtd
org/apache/tomcat/util/modeler/mbeans-descriptors.dtd
org/apache/tomcat/util/http/fileupload/package.html
I fully agree in getting rid of Date, Revision and Author.
I'm not so sure about using Id. Somehow I like the idea of being able to
identify a file version even if someone isolated from the context it has
been delivered in. I am talking about source files themselves, not about
generated javadoc.
As long as the file is part of an archive file or contained in an
extracted archive file directory structure, the version of the archive
corresponds to a tag and that is enough to know. But if someone copies a
file form there and isolates it from the rest of the file set, the Id
still tells you exactly what the contents are. Of course only as long as
the file itself is not changed.
So I like the idea of using Id, but I am open to arguments for dropping it.
Regards,
Rainer
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org