RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

mark.reinhold
8182776: Fix typo "upgradeble" in the javadoc of upgradeable modules
8183161: Remove extraneous font-family style attributes from module declarations
8183251: Meta "keywords" tag malformed in overview-summary.html and related pages

http://cr.openjdk.java.net/~mr/rev/8182776/jdk9-dev.patch
http://cr.openjdk.java.net/~mr/rev/8182776/api/ (sample output)

None of these is truly P1 but they're all fairly embarrassing and the
fixes are low-risk, so since we know we're going to do another build next
week anyway I'd like to include this patch.

The fix for 8183251 doesn't solve the problem of `<div>` occurring inside
`<h1>`, but this only ever happens in the frame-summary pages and appears
to do no harm when rendered.

This patch includes a few minor editorial fixes, e.g., changing `@link`
tags to `@linkplain` where appropriate in module declarations.

Thanks,
- Mark
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

Jonathan Gibbons
Mark,

The font-family settings in the <dl> nodes were deliberate, and a
workaround for not having time to create a proper taglet for tool guides.

If you remove the style attribute, you'll see in your sample output that
the "Tool Guides" header is in Serif font, but the immediately following
"Since: "  header is in the standard Sans Serif font.

See, for example, this page:
http://cr.openjdk.java.net/~mr/rev/8182776/api/jdk.compiler-summary.html

And for those that can see images in line:

Screnshot of mismatched header fonts

The screenshot has also been attached to the appropriate bug: JDK-8183161

I would recommend that JDK-8183161 should be "Not An Issue" and the
changes reverted in the proposed patch.

-- Jon

On 06/30/2017 02:36 PM, [hidden email] wrote:

> 8182776: Fix typo "upgradeble" in the javadoc of upgradeable modules
> 8183161: Remove extraneous font-family style attributes from module declarations
> 8183251: Meta "keywords" tag malformed in overview-summary.html and related pages
>
> http://cr.openjdk.java.net/~mr/rev/8182776/jdk9-dev.patch
> http://cr.openjdk.java.net/~mr/rev/8182776/api/ (sample output)
>
> None of these is truly P1 but they're all fairly embarrassing and the
> fixes are low-risk, so since we know we're going to do another build next
> week anyway I'd like to include this patch.
>
> The fix for 8183251 doesn't solve the problem of `<div>` occurring inside
> `<h1>`, but this only ever happens in the frame-summary pages and appears
> to do no harm when rendered.
>
> This patch includes a few minor editorial fixes, e.g., changing `@link`
> tags to `@linkplain` where appropriate in module declarations.
>
> Thanks,
> - Mark

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

mark.reinhold
2017/6/30 16:08:09 -0700, [hidden email]:

> Mark,
>
> The font-family settings in the <dl> nodes were deliberate, and a
> workaround for not having time to create a proper taglet for tool guides.
>
> If you remove the style attribute, you'll see in your sample output that
> the "Tool Guides" header is in Serif font, but the immediately following
> "Since: "  header is in the standard Sans Serif font.
>
> See, for example, this page:
> http://cr.openjdk.java.net/~mr/rev/8182776/api/jdk.compiler-summary.html

You're right, but the problem with placing the style attribute on the
`<dl>` elements is that it forces the `<dd>` text into the sans-serif
font.  That's fine for the tool-guide links, since they're tool names,
but it's wrong for provider descriptions, which are free text (see the
attached image).

The right fix is to repair the Javadoc stylesheet, but the expedient fix
is to tweak the style attributes just where needed, so I've updated the
patch to do the latter:

  http://cr.openjdk.java.net/~mr/rev/8182776/jdk9-dev.patch
  http://cr.openjdk.java.net/~mr/rev/8182776/api/ (sample output)

- Mark
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

Jonathan Gibbons


On 07/03/2017 10:52 AM, [hidden email] wrote:

> 2017/6/30 16:08:09 -0700, [hidden email]:
>> Mark,
>>
>> The font-family settings in the <dl> nodes were deliberate, and a
>> workaround for not having time to create a proper taglet for tool guides.
>>
>> If you remove the style attribute, you'll see in your sample output that
>> the "Tool Guides" header is in Serif font, but the immediately following
>> "Since: "  header is in the standard Sans Serif font.
>>
>> See, for example, this page:
>> http://cr.openjdk.java.net/~mr/rev/8182776/api/jdk.compiler-summary.html
> You're right, but the problem with placing the style attribute on the
> `<dl>` elements is that it forces the `<dd>` text into the sans-serif
> font.  That's fine for the tool-guide links, since they're tool names,
> but it's wrong for provider descriptions, which are free text (see the
> attached image).
>
> The right fix is to repair the Javadoc stylesheet, but the expedient fix
> is to tweak the style attributes just where needed, so I've updated the
> patch to do the latter:
>
>    http://cr.openjdk.java.net/~mr/rev/8182776/jdk9-dev.patch
>    http://cr.openjdk.java.net/~mr/rev/8182776/api/ (sample output)
>
> - Mark

Yes, understood. I hadn't realized that "Tool Guides" had been extended
to "Providers".

-- Jon
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

Jonathan Gibbons
In reply to this post by mark.reinhold
Looks good to me.

-- Jon


On 7/3/17 10:52 AM, [hidden email] wrote:

> 2017/6/30 16:08:09 -0700, [hidden email]:
>> Mark,
>>
>> The font-family settings in the <dl> nodes were deliberate, and a
>> workaround for not having time to create a proper taglet for tool guides.
>>
>> If you remove the style attribute, you'll see in your sample output that
>> the "Tool Guides" header is in Serif font, but the immediately following
>> "Since: "  header is in the standard Sans Serif font.
>>
>> See, for example, this page:
>> http://cr.openjdk.java.net/~mr/rev/8182776/api/jdk.compiler-summary.html
> You're right, but the problem with placing the style attribute on the
> `<dl>` elements is that it forces the `<dd>` text into the sans-serif
> font.  That's fine for the tool-guide links, since they're tool names,
> but it's wrong for provider descriptions, which are free text (see the
> attached image).
>
> The right fix is to repair the Javadoc stylesheet, but the expedient fix
> is to tweak the style attributes just where needed, so I've updated the
> patch to do the latter:
>
>    http://cr.openjdk.java.net/~mr/rev/8182776/jdk9-dev.patch
>    http://cr.openjdk.java.net/~mr/rev/8182776/api/ (sample output)
>
> - Mark

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR 8182776/8183161/8183251: Miscellaneous API doc fixes

Alan Bateman


On 03/07/2017 19:27, Jonathan Gibbons wrote:
> Looks good to me.
>
> -- Jon
Thumbs up from me too.

-Alan
Loading...