8016217: More javadoc warnings

[Alan Bateman]

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.

-Alan.