 and {@code with current jdk8 css
Message-ID: <308AA131-2400-4A14-B37E-B28A304C037E@oracle.com>

I have been working on javadoc for the JDK 8 lambda streams feature and ran across some interesting quirks in the current default javadoc css.

We have been using the construction 

{@code 
   ...
}

for block examples. We add the {@code} to the normal  block to avoid having to use html entities within the sample to escape the "&" and "<" characters. This makes the examples easier to read in the original source file.

The formatting of a  block and a {@code block is slightly different as a result relative sizing and nesting.

The  tag sets the font-size to 1.3em (stylesheet.css, line 31)

The  tag (emitted by {@code}) sets the font-size to 1.2em (stylesheet.css, line 55)

When nested the effective size is default * body (76%) * 1.3 (pre) * 1.2 (code). 

It would be nice if {@code} nested inside  didn't increase the size. Using relative sizes is generally going to be weird whenever nesting occurs especially if it can occur in more than one order.

Could  and  be made to use the same size? 

Might it be better to use "{@literal ... " than "{@code ..." as {@literal doesn't add any styles?

Out of curiosity:

- Why is the default body size 76% of the default text size? The 100% size is supposed the user's comfortable reading size. Other than for "fine print" why would we want to force a size smaller than that?
- An explicit font selection is made for body copy but none is made for code/pre text. Why not? Choosing a code font would allow better matching of the size of the body copy and mono space text. It would appear that for Arial/Courier that a 1.05em ratio is somewhat better than the 1.2em currently used.

Thanks,

Mike

From sven.reimers at gmail.com  Tue Jul 23 05:00:18 2013
From: sven.reimers at gmail.com (Sven Reimers)
Date: Tue, 23 Jul 2013 14:00:18 +0200
Subject: Possible inconsistency with auto generated javadoc on overridden
	elements
Message-ID: 

Hi,

since I got no response so far  (stuck in moderator queue) this is a retry
to get this through to the list.

I would assume that following the rules from

http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc
.html#inheritingcomments

the javadoc output of

public interface Test {

    void method();

    public abstract class AbstractEmptyTest implements Test {}

    public abstract class DefiningEmptyTest implements Test {
        @Override abstract public void method();
    }

    public class DirectTest implements Test {
        @Override public void method() {}
    }

    public class DefaultWithDefiningTest extends DefiningEmptyTest {
        @Override public void method() {}
    }

    public class DefaultWithEmptyTest extends AbstractEmptyTest {
        @Override public void method() {}
    }
}

should show at least a specified by link in the javadoc for method () on
all non abstract classes?

It seems to me that having an abstract class inbetween the concrete class
with the implementing method and the original interface, somehow the
specified by is not resolved.

Any comments? Shall I file a bug? Did I misread the spec?

Thanks

-Sven

P.S. Hope this makes it through this time.
-- 
Sven Reimers

* Senior Expert Software Architect
* NetBeans Dream Team Member: http://dreamteam.netbeans.org
* Community Leader  NetBeans: http://community.java.net/netbeans
                              Desktop Java:
http://community.java.net/javadesktop
* Duke's Choice Award Winner 2009

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130723/a70201cb/attachment.html 

From jonathan.gibbons at oracle.com  Tue Jul 23 11:56:35 2013
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 23 Jul 2013 11:56:35 -0700
Subject: javadoc TLC update
Message-ID: <51EED1E3.9030900@oracle.com>

FYI, Sean Hogan has posted an interesting followup comment [1] to my 
recent blog entry on javadoc TLC.  He demos how to use AJAX and 
pushState to provide an improved javadoc viewer that does not use frames.

-- Jon

[1] https://blogs.oracle.com/jjg/entry/javadoc_tlc#comment-1374553083469

From martinrb at google.com  Wed Jul 24 17:50:09 2013
From: martinrb at google.com (Martin Buchholz)
Date: Wed, 24 Jul 2013 17:50:09 -0700
Subject: Sizing of  and {@code with current jdk8 css
In-Reply-To: <308AA131-2400-4A14-B37E-B28A304C037E@oracle.com>
References: <308AA131-2400-4A14-B37E-B28A304C037E@oracle.com>
Message-ID: 

You're not the only one annoyed by the giant sample code font.  I agree
with you that the "regular" text should be regular text size, and the
sample text not too much different - that's why we have different fonts!
 CSS owners, please fix!

On Mon, Jul 22, 2013 at 4:14 PM, Mike Duigou  wrote:

> I have been working on javadoc for the JDK 8 lambda streams feature and
> ran across some interesting quirks in the current default javadoc css.
>
> We have been using the construction
>
> {@code
>    ...
> }
>
> for block examples. We add the {@code} to the normal  block to avoid
> having to use html entities within the sample to escape the "&" and "<"
> characters. This makes the examples easier to read in the original source
> file.
>
> The formatting of a  block and a {@code block is slightly
> different as a result relative sizing and nesting.
>
> The  tag sets the font-size to 1.3em (stylesheet.css, line 31)
>
> The  tag (emitted by {@code}) sets the font-size to 1.2em
> (stylesheet.css, line 55)
>
> When nested the effective size is default * body (76%) * 1.3 (pre) * 1.2
> (code).
>
> It would be nice if {@code} nested inside  didn't increase the size.
> Using relative sizes is generally going to be weird whenever nesting occurs
> especially if it can occur in more than one order.
>
> Could  and  be made to use the same size?
>
> Might it be better to use "{@literal ... " than "{@code ..." as
> {@literal doesn't add any styles?
>
> Out of curiosity:
>
> - Why is the default body size 76% of the default text size? The 100% size
> is supposed the user's comfortable reading size. Other than for "fine
> print" why would we want to force a size smaller than that?
> - An explicit font selection is made for body copy but none is made for
> code/pre text. Why not? Choosing a code font would allow better matching of
> the size of the body copy and mono space text. It would appear that for
> Arial/Courier that a 1.05em ratio is somewhat better than the 1.2em
> currently used.
>
> Thanks,
>
> Mike
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130724/a6c11a3d/attachment.html 

From jonathan.gibbons at oracle.com  Wed Jul 24 18:23:08 2013
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 24 Jul 2013 18:23:08 -0700
Subject: Sizing of  and {@code with current jdk8 css
In-Reply-To: 
References: <308AA131-2400-4A14-B37E-B28A304C037E@oracle.com>

Message-ID: <51F07DFC.2030903@oracle.com>

I'll take that as a bug report...

-- Jon

On 07/24/2013 05:50 PM, Martin Buchholz wrote:
> You're not the only one annoyed by the giant sample code font.  I 
> agree with you that the "regular" text should be regular text size, 
> and the sample text not too much different - that's why we have 
> different fonts!  CSS owners, please fix!
>
>
> On Mon, Jul 22, 2013 at 4:14 PM, Mike Duigou  > wrote:
>
>     I have been working on javadoc for the JDK 8 lambda streams
>     feature and ran across some interesting quirks in the current
>     default javadoc css.
>
>     We have been using the construction
>
>     {@code
>        ...
>     }
>
>     for block examples. We add the {@code} to the normal  block
>     to avoid having to use html entities within the sample to escape
>     the "&" and "<" characters. This makes the examples easier to read
>     in the original source file.
>
>     The formatting of a  block and a {@code block is
>     slightly different as a result relative sizing and nesting.
>
>     The  tag sets the font-size to 1.3em (stylesheet.css, line 31)
>
>     The  tag (emitted by {@code}) sets the font-size to 1.2em
>     (stylesheet.css, line 55)
>
>     When nested the effective size is default * body (76%) * 1.3 (pre)
>     * 1.2 (code).
>
>     It would be nice if {@code} nested inside  didn't increase
>     the size. Using relative sizes is generally going to be weird
>     whenever nesting occurs especially if it can occur in more than
>     one order.
>
>     Could  and  be made to use the same size?
>
>     Might it be better to use "{@literal ... " than "{@code
>     ..." as {@literal doesn't add any styles?
>
>     Out of curiosity:
>
>     - Why is the default body size 76% of the default text size? The
>     100% size is supposed the user's comfortable reading size. Other
>     than for "fine print" why would we want to force a size smaller
>     than that?
>     - An explicit font selection is made for body copy but none is
>     made for code/pre text. Why not? Choosing a code font would allow
>     better matching of the size of the body copy and mono space text.
>     It would appear that for Arial/Courier that a 1.05em ratio is
>     somewhat better than the 1.2em currently used.
>
>     Thanks,
>
>     Mike
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130724/b8b50393/attachment.html 

From jonathan.gibbons at oracle.com  Wed Jul 24 18:38:46 2013
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 24 Jul 2013 18:38:46 -0700
Subject: Sizing of  and {@code with current jdk8 css
In-Reply-To: <51F07DFC.2030903@oracle.com>
References: <308AA131-2400-4A14-B37E-B28A304C037E@oracle.com>

	<51F07DFC.2030903@oracle.com>
Message-ID: <51F081A6.2040304@oracle.com>

Issue 8021313, should be available on bugs.sun.com soon.

-- Jon

On 07/24/2013 06:23 PM, Jonathan Gibbons wrote:
> I'll take that as a bug report...
>
> -- Jon
>
> On 07/24/2013 05:50 PM, Martin Buchholz wrote:
>> You're not the only one annoyed by the giant sample code font.  I 
>> agree with you that the "regular" text should be regular text size, 
>> and the sample text not too much different - that's why we have 
>> different fonts!  CSS owners, please fix!
>>
>>
>> On Mon, Jul 22, 2013 at 4:14 PM, Mike Duigou > > wrote:
>>
>>     I have been working on javadoc for the JDK 8 lambda streams
>>     feature and ran across some interesting quirks in the current
>>     default javadoc css.
>>
>>     We have been using the construction
>>
>>     {@code
>>        ...
>>     }
>>
>>     for block examples. We add the {@code} to the normal  block
>>     to avoid having to use html entities within the sample to escape
>>     the "&" and "<" characters. This makes the examples easier to
>>     read in the original source file.
>>
>>     The formatting of a  block and a {@code block is
>>     slightly different as a result relative sizing and nesting.
>>
>>     The  tag sets the font-size to 1.3em (stylesheet.css, line 31)
>>
>>     The  tag (emitted by {@code}) sets the font-size to 1.2em
>>     (stylesheet.css, line 55)
>>
>>     When nested the effective size is default * body (76%) * 1.3
>>     (pre) * 1.2 (code).
>>
>>     It would be nice if {@code} nested inside  didn't increase
>>     the size. Using relative sizes is generally going to be weird
>>     whenever nesting occurs especially if it can occur in more than
>>     one order.
>>
>>     Could  and  be made to use the same size?
>>
>>     Might it be better to use "{@literal ... " than "{@code
>>     ..." as {@literal doesn't add any styles?
>>
>>     Out of curiosity:
>>
>>     - Why is the default body size 76% of the default text size? The
>>     100% size is supposed the user's comfortable reading size. Other
>>     than for "fine print" why would we want to force a size smaller
>>     than that?
>>     - An explicit font selection is made for body copy but none is
>>     made for code/pre text. Why not? Choosing a code font would allow
>>     better matching of the size of the body copy and mono space text.
>>     It would appear that for Arial/Courier that a 1.05em ratio is
>>     somewhat better than the 1.2em currently used.
>>
>>     Thanks,
>>
>>     Mike
>>
>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130724/ba36758f/attachment.html 