Am 13.09.2015 um 16:46 schrieb Konstantin Kolinko:
2015-09-13 17:09 GMT+03:00 <fschumac...@apache.org>:
Author: fschumacher
Date: Sun Sep 13 14:09:24 2015
New Revision: 1702779
URL: http://svn.apache.org/r1702779
Log:
Javadocs. Convert xml fragment to {@code ... } and correct the xml example.
Merge r1702778 from /tomcat/trunk
Modified:
tomcat/tc8.0.x/trunk/ (props changed)
tomcat/tc8.0.x/trunk/java/org/apache/catalina/storeconfig/StoreLoader.java
Modified:
tomcat/tc8.0.x/trunk/java/org/apache/catalina/storeconfig/StoreLoader.java
URL:
http://svn.apache.org/viewvc/tomcat/tc8.0.x/trunk/java/org/apache/catalina/storeconfig/StoreLoader.java?rev=1702779&r1=1702778&r2=1702779&view=diff
==============================================================================
--- tomcat/tc8.0.x/trunk/java/org/apache/catalina/storeconfig/StoreLoader.java
(original)
+++ tomcat/tc8.0.x/trunk/java/org/apache/catalina/storeconfig/StoreLoader.java
Sun Sep 13 14:09:24 2015
@@ -31,21 +31,24 @@ import org.xml.sax.SAXException;
* <b>XML Format </b>
*
* <pre>
- *
- * <Registry name="" encoding="UTF8" >
- * <Description tag="Server" standard="true"
default="true"/>
- * tagClass="org.apache.catalina.core.StandardServer"
- *
storeFactory="org.apache.catalina.storeconfig.StandardServerSF">
- * <TransientAttributes>
- * <Attribute></Attribute>
- * </TransientAttributes>
- * <TransientChildren>
- * <Child></Child>
- * </TransientChildren>
- * </Description>
+ * {@code
+ * <Registry name="" encoding="UTF8" >
+ * <Description
+ * tag="Server"
+ * standard="true"
+ * default="true"
+ * tagClass="org.apache.catalina.core.StandardServer"
+ *
storeFactoryClass="org.apache.catalina.storeconfig.StandardServerSF">
+ * <TransientAttributes>
+ * <Attribute></Attribute>
+ * </TransientAttributes>
+ * <TransientChildren>
+ * <Child></Child>
+ * </TransientChildren>
+ * </Description>
* ...
- * </Tegistry>
- *
+ * </Registry>
+ * }
* </pre>
*
*
It is rather odd to use {@code } for multi-line text.
As one can use <, > and " instead of quoting them, I think it is a nice
usage of @code.
Is it an officially recommended practice?
Don't really know, but I found a bug entry
https://bugs.openjdk.java.net/browse/JDK-8017326, which indicates, that
it is good practice to use @code rather than code.
Is there an example of such use in JDK source code?
It is used in multiple places in the jdk 9 sources. In
./javax/xml/crypto/dsig/Manifest.java for example, it is used for
xml-fragments like the above one.
In my opinion, {@code} is like <code> markup, which is an inline
markup element. Using it for long multi-line fragments of text is odd.
Is javadoc processor free to collapse adjacent spaces in such
fragments (breaking formatting), or it preserves the formatting?
The javadoc processor would collapse all spaces, where it not for the
added pre-tags. code and @code will behave the same in that respect.
Note that you cannot use '}' character inside the fragment (as it
terminates the {@code } block). So while this trick was useful for
XML, it cannot be used for long fragments of Java code that use
'{..}' blocks.
Well the example from PagedResultsControl (in jdk 8), seems to show,
that one can use } inside the @code block. But I have to admit, that I
don't know the exact rules, when it is ok to use it.
Technical:
I see no complaints for StoreLoader class by javadoc lint of Java 8
both before and after this change,
https://ci.apache.org/builders/tomcat-trunk/builds/227/steps/compile/logs/stdio
https://ci.apache.org/builders/tomcat-trunk/builds/249/steps/compile/logs/stdio
So it did not increase the number of javadoc warnings when building
with java 8, but it did not decrease their number either. So this
change was not justified by javadoc warnings.
It was not javadoc warnings, that led me to the change, but rather
readability. I find it quite confusing to "parse" the < as <. And the
xml fragment contained two errors, which might have been seen earlier
otherwise.
I have not reviewed the actual javadoc generated by this change.
Documentation published by Buildbot does not include javadoc, so I'd
need to build it locally.
Thanks for reviewing. In my tests the generated javadocs where ok.
Best regards,
Felix
So I do not see any technical issues yet.
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
