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.
Is it an officially recommended practice?
Is there an example of such use in JDK source code?
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?
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.
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.
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.
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
