8016217: More javadoc warnings

[Joe Darcy]

On 6/11/2013 5:33 AM, Alan Bateman wrote:
> On 11/06/2013 13:08, Sean Mullan wrote:
>> The changes to classes in the security component look fine. One 
>> question I have is about the change to 
>> javax/xml/crypto/dsig/Manifest.java. Was there a specific error here 
>> or did you just want to make this cleaner by removing all of the html 
>> special character handling? The reason I ask is that there are many 
>> other classes in javax.xml.crypto which have similar javadoc 
>> sections, so I am wondering if they have similar issues.
> The error was at line 41:
>
> * <sequence>
>
> The > should have been >
>
> There are several other examples of the same thing. Also there are 
> several cases (in other areas) where there was an attempt to use < 
> or > but the semicolon was left out.
>
> So for this case then I could have fixed it by using > but since 
> this is XML schema definition then I personally think it's a lot more 
> readable to have the original XML in {@code ...}. Another example is 
> the DTD in java/util/Preferences.java where the error was a missing 
> semi-colon, in that case it seems more readable (to me anyway) to have 
> the DTD passed in. Same thing for code examples that have type 
> parameters. As I mentioned in one of the mails yesterday (and I think 
> Mike's mail is agreeing) it is very tempting to replace all 
> <code></code> usages with {@code ...}. This would require un-doing 
> existing escaping but the result should be more readable and less 
> error-pone when edited.

I would support (and even help review!) a  bulk change of 
<code>foo</code> to {@code foo}. Whenever I look at <code>foo</code>, my 
eyes hurt. IIRC, there are a few cases which require HTML escaping, like 
trying to output a fixed-width "@" character, but they are a very small 
minority.

-Joe