8017325, 8017326: Cleanup of javadoc <code> tag

[Joseph Darcy]

On 6/24/2013 3:00 PM, Jason Uh wrote:
>
>
> On 6/24/13 10:51 AM, Joe Darcy wrote:
>> Hi Jason,
>>
>> On 6/21/2013 6:58 PM, Jason Uh wrote:
>>> After learning that javadoc is now capable of properly formatting the
>>> "<pre>{@code ...}</pre>" construct, I have updated the changeset for
>>> java.security.cert. Please review instead:
>>>
>>> Webrevs --
>>> - java.security.cert (updated):
>>>     http://cr.openjdk.java.net/~juh/8017325/webrev.01/
>>> - java.security.spec (no change):
>>>     http://cr.openjdk.java.net/~juh/8017326/webrev.00/
>>
>> I've looked over both patches and they look fine.
>>
>> However, as a follow-up, please also expand the conversion to include
>> mapping "<tt>foo</tt>" => "{@code foo}".
>
> Thanks. I can make those changes, but are you suggesting that I add 
> them to this changeset or that I do that separately?

For review purposes, I'd like to see them separately in some fashion, 
even if it was produced by diffing the patch files.

>
>>>
>>> Note that this change does visibly change the generated javadoc, as
>>> reported by specdiff. In particular, the change to <pre>{@code
>>> ...}</pre> in the javadoc for the
>>> X509Extension.getNonCriticalExtensionOIDs() method now allows the
>>> generated HTML to correctly display the line:
>>>
>>>    Set<String> nonCritSet = badCert.getNonCriticalExtensionOIDs();
>>>
>>> which was previously (incorrectly) displayed as
>>>
>>>    Set nonCritSet = badCert.getNonCriticalExtensionOIDs();
>>>
>>> when the text "<String>" was still enclosed within
>>> "<pre><code>...</code></pre>".
>>
>> Running specdiff is a good double-check in this situation.
>>
>> Should the scripts you are using here to placed somewhere in the JDK
>> repo or in the code tools project?
>
> I'm not sure that I follow. Are you requesting that I include 
> somewhere in the repo the line of Perl that I ran? (It was used to 
> make most, but not all of these changes.) If so, where would be the 
> most appropriate place to add that?

If it is a one-liner, it could be included in the summary line of the 
commit message or as a comment in the bug. If it is more substantive 
(since we will be rolling out this change across the JDK libraries), 
having the command in a known-location would be helpful. Especially, if 
a check for this pattern is built into future code-quality checks.

-Joe

>
> Thanks,
> Jason
>
>> Thanks,
>>
>> -Joe
>>
>>>
>>> Thanks,
>>> Jason
>>>
>>>
>>> The files that have been updated
>>>
>>> On 6/21/13 5:47 PM, Jason Uh wrote:
>>>> Joe, all,
>>>>
>>>> Could I please get a review of the following changes?
>>>>
>>>> These changesets convert the <code>...</code> javadoc tags to {@code
>>>> ...} as part of an overall effort to clean up doclint warnings.
>>>>
>>>> Webrevs --
>>>> - java.security.cert:
>>>>      http://cr.openjdk.java.net/~juh/8017325/webrev.00/
>>>> - java.security.spec:
>>>>      http://cr.openjdk.java.net/~juh/8017326/webrev.00/
>>>>
>>>> specdiff reported no changes in the generated docs.
>>>>
>>>> More of these to come.
>>>>
>>>> Thanks,
>>>> Jason
>>>
>>
>