Upcoming 2.9.0.RC1 (take 2)

>>>>> "Antonio" == Antonio Cunei writes:

Antonio> Anything else? Please let me know if you have additional
Antonio> issues that should definitely be addressed before 2.9.0, or if
Antonio> there is any further code that you think should go in and that
Antonio> is currently still pending.

I reviewed my list of watched tickets and the only one that jumped out
at me as possibly missing from your list is
http://lampsvn.epfl.ch/trac/scala/ticket/2671

fwiw, NetLogo seems to be running fine on the recent nightlies.
Libraries and tools we're using with 2.9 include sbt, ScalaTest,
ScalaCheck, and ProGuard.

On 16/03/2011 23:41, Seth Tisue wrote:
> I reviewed my list of watched tickets and the only one that jumped out
> at me as possibly missing from your list is
> http://lampsvn.epfl.ch/trac/scala/ticket/2671
>

Absolutely, thanks! I actually meant to include this one rather than
#4248 (but #4248 will be addressed as well).

> fwiw, NetLogo seems to be running fine on the recent nightlies.
> Libraries and tools we're using with 2.9 include sbt, ScalaTest,
> ScalaCheck, and ProGuard.
>

Excellent! :)
Thanks,
Toni

I'm not sure what the priority is, but this one blocks Scala from using a few of our libs at work: https://lampsvn.epfl.ch/trac/scala/ticket/4283

On Wed, Mar 16, 2011 at 6:52 PM, Antonio Cunei <antonio.cunei@epfl.ch> wrote:

On 16/03/2011 23:41, Seth Tisue wrote:

I reviewed my list of watched tickets and the only one that jumped out
at me as possibly missing from your list is
http://lampsvn.epfl.ch/trac/scala/ticket/2671

Absolutely, thanks! I actually meant to include this one rather than #4248 (but #4248 will be addressed as well).

fwiw, NetLogo seems to be running fine on the recent nightlies.
Libraries and tools we're using with 2.9 include sbt, ScalaTest,
ScalaCheck, and ProGuard.

Excellent! :)
Thanks,
Toni

Unfortunately, according to Martin at last week's meeting, this one will be quite complicated to fix, due to the phase in which the cast is inserted. Since it requires such a big change, I strongly doubt it can be fixed for 2.9.0.
Donna
On Mar 17, 2011, at 1:25 AM, Josh Suereth wrote:

I'm not sure what the priority is, but this one blocks Scala from using a few of our libs at work: https://lampsvn.epfl.ch/trac/scala/ticket/4283

On Wed, Mar 16, 2011 at 6:52 PM, Antonio Cunei <antonio.cunei@epfl.ch> wrote:

On 16/03/2011 23:41, Seth Tisue wrote:

I reviewed my list of watched tickets and the only one that jumped out
at me as possibly missing from your list is
http://lampsvn.epfl.ch/trac/scala/ticket/2671

Absolutely, thanks! I actually meant to include this one rather than #4248 (but #4248 will be addressed as well).

fwiw, NetLogo seems to be running fine on the recent nightlies.
Libraries and tools we're using with 2.9 include sbt, ScalaTest,
ScalaCheck, and ProGuard.

Excellent! :)
Thanks,
Toni

Hi Antonio,

Is there a Maven repo with the latest 2.9.0 build? I keep hearing
people mention 2.9.0-SNAPSHOT, but I can't find any info on where it
is on scala-lang.org.

Thanks.

Bill

On Wed, Mar 16, 2011 at 3:03 PM, Antonio Cunei wrote:
> All,
>
> After a bit of additional time spent on fixing tickets and improving
> features, we are aiming to get an RC1 release next week.
>
> According to the messages I have seen so far, and the present status of the
> code, I currently have this list of tickets that are still open, and that
> various people considered important to address before the release of RC1:
>
> http://lampsvn.epfl.ch/trac/scala/ticket/4205 (assigned moors)
> http://lampsvn.epfl.ch/trac/scala/ticket/4202 (assigned plocinic)
> http://lampsvn.epfl.ch/trac/scala/ticket/4012 (assigned dragos)
> http://lampsvn.epfl.ch/trac/scala/ticket/4248 (assigned cunei)
> http://lampsvn.epfl.ch/trac/scala/ticket/3623 (assigned extempore)
> http://lampsvn.epfl.ch/trac/scala/ticket/4214 (assigned extempore)
> http://lampsvn.epfl.ch/trac/scala/ticket/4305 (assigned moors)
> http://lampsvn.epfl.ch/trac/scala/ticket/4337 (pending)
>
> Anything else? Please let me know if you have additional issues that should
> definitely be addressed before 2.9.0, or if there is any further code that
> you think should go in and that is currently still pending.
>
> Thanks!
> Toni
>

Hi Bill,

It's on scala-tools.org:

http://scala-tools.org/repo-snapshots/org/scala-lang/scala-compiler/2.9....

You are right that it is not very visible on scala-lang; I'll add this
information to the page on nightly builds.
Toni

On 17/03/2011 06:59, Bill Venners wrote:
> Hi Antonio,
>
> Is there a Maven repo with the latest 2.9.0 build? I keep hearing
> people mention 2.9.0-SNAPSHOT, but I can't find any info on where it
> is on scala-lang.org.
>
> Thanks.
>
> Bill
>
> On Wed, Mar 16, 2011 at 3:03 PM, Antonio Cunei wrote:
>> All,
>>
>> After a bit of additional time spent on fixing tickets and improving
>> features, we are aiming to get an RC1 release next week.
>>
>> According to the messages I have seen so far, and the present status of the
>> code, I currently have this list of tickets that are still open, and that
>> various people considered important to address before the release of RC1:
>>
>> http://lampsvn.epfl.ch/trac/scala/ticket/4205 (assigned moors)
>> http://lampsvn.epfl.ch/trac/scala/ticket/4202 (assigned plocinic)
>> http://lampsvn.epfl.ch/trac/scala/ticket/4012 (assigned dragos)
>> http://lampsvn.epfl.ch/trac/scala/ticket/4248 (assigned cunei)
>> http://lampsvn.epfl.ch/trac/scala/ticket/3623 (assigned extempore)
>> http://lampsvn.epfl.ch/trac/scala/ticket/4214 (assigned extempore)
>> http://lampsvn.epfl.ch/trac/scala/ticket/4305 (assigned moors)
>> http://lampsvn.epfl.ch/trac/scala/ticket/4337 (pending)
>>
>> Anything else? Please let me know if you have additional issues that should
>> definitely be addressed before 2.9.0, or if there is any further code that
>> you think should go in and that is currently still pending.
>>
>> Thanks!
>> Toni
>>
>
>
>

Hi,

This bug has been reclassified as an enhancement, but this is clearly a bug:

https://lampsvn.epfl.ch/trac/scala/ticket/4233

If you look at just about any class or trait in this documentation,
which I built off of 2.9.0-SNAPSHOT, at least on Safari on the Mac,
you get a complete duplicate of the entire class or trait
documentation. The second one is indented slightly.

http://www.artima.com/scaladocprobs/

I did discover tonight that if I click in just the right place, the
lower one disappears magically. But I had to really hunt for that.
When I click again the whole thing bounces and then moves into a
different position, but still doesn't show the second copy. It took me
months before I realized if I clicked in one spot the duplicate copy
would vanish.

In the method descriptions there's also duplication. It looks really
stupid and amateurish. If this can't be fixed in JavaScript then you
should dump the JavaScript. JavaDoc works just fine by showing a table
of summaries and when you click on one it hops to a spot farther down
that has the detailed description. By trying to fix something that
wasn't broken you broke something that worked.

A few more that we will report as bugs tomorrow are:

1. — shows up in the output rather than being used as an HTML
entity. An example is here (search for 8212):

http://www.artima.com/scaladocprobs/org/scalatest/matchers/MatchResult.html

“ and ” have the same problem. An example is on this page
(search for 8221):

http://www.artima.com/scaladocprobs/org/scalatest/FunSuite.html

We submitted a bug report that entities weren't working inside

sections which may have been fixed, but if so we should have simply
said HTML entities don't work.

2. i.e. causes everything after the i. in the same paragraph
to be dropped, and the rest of the entire page to show up in italics.
An example is on the call method documentation on this page:

http://www.artima.com/scaladocprobs/org/scalatest/mock/EasyMockSugar.html

3. Any equals method has this:

The default implementations of this method is an
[http://en.wikipedia.org/wiki/Equivalence_relation equivalence
relation]: * It is reflexive: for any instance x of type Any,
x.equals(x) should return true. * It is symmetric: for any instances x
and y of type Any, x.equals(y) should return true if and only if
y.equals(x) returns true. * It is transitive: for any instances x, y,
and z of type AnyRef if x.equals(y) returns true and y.equals(z)
returns true, then x.equals(z) should return true.

Nice link to wikipedia there, except it isn't a link.

4. In JMockSugar. some of the methods take a Matcher, but it just says
Matcher. Well that's a org.hamcrest.Matcher, not a
org.scalatest.Matcher, and there's no way to tell from the
documentation. Example:

http://www.artima.com/scaladocprobs/org/scalatest/mock/JMockExpectations...

So probably there's a general problem with figuring out when to show a
fully qualified name and when not to.

5. I have carat symbols (^) in the code examples on this page:

http://www.artima.com/scaladocprobs/org/scalatest/verb/CanVerb.html

But they are just dropped from the output. I use them to point to
things all over the place. You can see the same thing here:

http://www.artima.com/scaladocprobs/org/scalatest/matchers/Matchers$ResultOfNotWordForTraversable.html

In the ScalaDoc source I point to the exact part of the DSL syntax
that each method supports. And that's thrown away.

I've spent a lot of time today looking through trying to find
remaining problems, but I've probably missed some. In 2.8 several
large swaths of documentation were just dropped from the output, and I
didn't notice for a long time. I think those bugs are fixed. But
hopefully there aren't too many things I've missed.

I've gotten the vibe from EPFL that something like documentation is
very low priority. I understand they aren't as important as parallel
collecitons. But all these problems made ScalaTest much harder to use
since 2.8, and I think the state of Scaladoc in general reflects badly
on Scala itself. We'll submit more bugs tomorrow, and I hope you can
fix them  in 2.9.0, because i don't think they'll take long to fix and
they are in a tool off to the side.

Thanks.

Bill

On Wed, Mar 16, 2011 at 3:03 PM, Antonio Cunei 
 wrote:
> All,
>
> After a bit of additional time spent on fixing tickets and improving
> features, we are aiming to get an RC1 release next week.
>
> According to the messages I have seen so far, and the present status of the
> code, I currently have this list of tickets that are still open, and that
> various people considered important to address before the release of RC1:
>
> http://lampsvn.epfl.ch/trac/scala/ticket/4205 (assigned moors)
> http://lampsvn.epfl.ch/trac/scala/ticket/4202 (assigned plocinic)
> http://lampsvn.epfl.ch/trac/scala/ticket/4012 (assigned dragos)
> http://lampsvn.epfl.ch/trac/scala/ticket/4248 (assigned cunei)
> http://lampsvn.epfl.ch/trac/scala/ticket/3623 (assigned extempore)
> http://lampsvn.epfl.ch/trac/scala/ticket/4214 (assigned extempore)
> http://lampsvn.epfl.ch/trac/scala/ticket/4305 (assigned moors)
> http://lampsvn.epfl.ch/trac/scala/ticket/4337 (pending)
>
> Anything else? Please let me know if you have additional issues that should
> definitely be addressed before 2.9.0, or if there is any further code that
> you think should go in and that is currently still pending.
>
> Thanks!
> Toni
>

Hi, I'm Kato Kazuyoshi. non-EPFL committer of Scaladoc.

On Fri, Mar 18, 2011 at 12:26 PM, Bill Venners wrote:
>
> This bug has been reclassified as an enhancement, but this is clearly a bug:
>
> https://lampsvn.epfl.ch/trac/scala/ticket/4233
>
> If you look at just about any class or trait in this documentation,
> which I built off of 2.9.0-SNAPSHOT, at least on Safari on the Mac,
> you get a complete duplicate of the entire class or trait
> documentation. The second one is indented slightly.
>
> http://www.artima.com/scaladocprobs/
>
> I did discover tonight that if I click in just the right place, the
> lower one disappears magically. But I had to really hunt for that.
> When I click again the whole thing bounces and then moves into a
> different position, but still doesn't show the second copy. It took me
> months before I realized if I clicked in one spot the duplicate copy
> would vanish.
>
> In the method descriptions there's also duplication. It looks really
> stupid and amateurish. If this can't be fixed in JavaScript then you
> should dump the JavaScript. JavaDoc works just fine by showing a table
> of summaries and when you click on one it hops to a spot farther down
> that has the detailed description. By trying to fix something that
> wasn't broken you broke something that worked.
>

Very sorry. I'll fix this as soon as possible.

> A few more that we will report as bugs tomorrow are:
>
> 1. — shows up in the output rather than being used as an HTML
> entity. An example is here (search for 8212):
>
> http://www.artima.com/scaladocprobs/org/scalatest/matchers/MatchResult.html
>
> “ and ” have the same problem. An example is on this page
> (search for 8221):
>
> http://www.artima.com/scaladocprobs/org/scalatest/FunSuite.html
>
> We submitted a bug report that entities weren't working inside

> sections which may have been fixed, but if so we should have simply
> said HTML entities don't work.
>
> 2. i.e. causes everything after the i. in the same paragraph
> to be dropped, and the rest of the entire page to show up in italics.
> An example is on the call method documentation on this page:
>
> http://www.artima.com/scaladocprobs/org/scalatest/mock/EasyMockSugar.html
>
> 3. Any equals method has this:
>
> The default implementations of this method is an
> [http://en.wikipedia.org/wiki/Equivalence_relation equivalence
> relation]: * It is reflexive: for any instance x of type Any,
> x.equals(x) should return true. * It is symmetric: for any instances x
> and y of type Any, x.equals(y) should return true if and only if
> y.equals(x) returns true. * It is transitive: for any instances x, y,
> and z of type AnyRef if x.equals(y) returns true and y.equals(z)
> returns true, then x.equals(z) should return true.
>
> Nice link to wikipedia there, except it isn't a link.
>
> 4. In JMockSugar. some of the methods take a Matcher, but it just says
> Matcher. Well that's a org.hamcrest.Matcher, not a
> org.scalatest.Matcher, and there's no way to tell from the
> documentation. Example:
>
> http://www.artima.com/scaladocprobs/org/scalatest/mock/JMockExpectations...
>
> So probably there's a general problem with figuring out when to show a
> fully qualified name and when not to.
>
> 5. I have carat symbols (^) in the code examples on this page:
>
> http://www.artima.com/scaladocprobs/org/scalatest/verb/CanVerb.html
>
> But they are just dropped from the output. I use them to point to
> things all over the place. You can see the same thing here:
>
> http://www.artima.com/scaladocprobs/org/scalatest/matchers/Matchers$ResultOfNotWordForTraversable.html
>

Thank you for reporting. I'll see these problems.

> I've gotten the vibe from EPFL that something like documentation is
> very low priority. I understand they aren't as important as parallel
> collecitons. But all these problems made ScalaTest much harder to use
> since 2.8, and I think the state of Scaladoc in general reflects badly
> on Scala itself. We'll submit more bugs tomorrow, and I hope you can
> fix them  in 2.9.0, because i don't think they'll take long to fix and
> they are in a tool off to the side.

I can't feel the vibe. Probably, Switzerland is too far from Japan :)

Regards,

Antonio,

This one http://lampsvn.epfl.ch/trac/scala/ticket/4350 is related to:

> http://lampsvn.epfl.ch/trac/scala/ticket/4248 (assigned cunei)

Maybe it would be possible to fix them both together.
Do you need any help on any of them? I created both of them actually.

Regards
Grzegorz Balcerek

Hi Kato,

Thanks. Sorry everyone for the tone of my email. I was frustrated to
find more problems yesterday when I went through ScalaTest's ScalaDoc
output with the latest 2.9.0-SNAPSHOT. I'll ask Darlene to submit the
new ones as bug reports through Trac later today so they'll be
official. Several are quite minor, but also fixing them should be
quick and easy and low risk. But I also understand that it is last
minute before the release so some could have to wait until next
release.

Another thing I did in ScalaTest 1.3 was replace a few parts of the
CSS file generated by ScalaDoc to try and improve the readability and
fix issues I could fix. I increased the distance between paragraphs
for example. I think I had to make a change to make strong actually
show up as bold, and to turn off an underline on things.
I also changed to a serif font to better distinguish the difference
between text and code font, but that kind of thing I don't mind doing
myself. I'll try and dig up what changes I made and submit that as a
suggestion as well. If I had more time I'd pitch in to help with
ScalaDoc, but unfortunately I just haven't been able to find the time
to do that this year.

Bill

On Fri, Mar 18, 2011 at 1:28 AM, Kato Kazuyoshi
wrote:
> Hi, I'm Kato Kazuyoshi. non-EPFL committer of Scaladoc.
>
> On Fri, Mar 18, 2011 at 12:26 PM, Bill Venners wrote:
>>
>> This bug has been reclassified as an enhancement, but this is clearly a bug:
>>
>> https://lampsvn.epfl.ch/trac/scala/ticket/4233
>>
>> If you look at just about any class or trait in this documentation,
>> which I built off of 2.9.0-SNAPSHOT, at least on Safari on the Mac,
>> you get a complete duplicate of the entire class or trait
>> documentation. The second one is indented slightly.
>>
>> http://www.artima.com/scaladocprobs/
>>
>> I did discover tonight that if I click in just the right place, the
>> lower one disappears magically. But I had to really hunt for that.
>> When I click again the whole thing bounces and then moves into a
>> different position, but still doesn't show the second copy. It took me
>> months before I realized if I clicked in one spot the duplicate copy
>> would vanish.
>>
>> In the method descriptions there's also duplication. It looks really
>> stupid and amateurish. If this can't be fixed in JavaScript then you
>> should dump the JavaScript. JavaDoc works just fine by showing a table
>> of summaries and when you click on one it hops to a spot farther down
>> that has the detailed description. By trying to fix something that
>> wasn't broken you broke something that worked.
>>
>
> Very sorry. I'll fix this as soon as possible.
>
>> A few more that we will report as bugs tomorrow are:
>>
>> 1. — shows up in the output rather than being used as an HTML
>> entity. An example is here (search for 8212):
>>
>> http://www.artima.com/scaladocprobs/org/scalatest/matchers/MatchResult.html
>>
>> “ and ” have the same problem. An example is on this page
>> (search for 8221):
>>
>> http://www.artima.com/scaladocprobs/org/scalatest/FunSuite.html
>>
>> We submitted a bug report that entities weren't working inside

>> sections which may have been fixed, but if so we should have simply
>> said HTML entities don't work.
>>
>> 2. i.e. causes everything after the i. in the same paragraph
>> to be dropped, and the rest of the entire page to show up in italics.
>> An example is on the call method documentation on this page:
>>
>> http://www.artima.com/scaladocprobs/org/scalatest/mock/EasyMockSugar.html
>>
>> 3. Any equals method has this:
>>
>> The default implementations of this method is an
>> [http://en.wikipedia.org/wiki/Equivalence_relation equivalence
>> relation]: * It is reflexive: for any instance x of type Any,
>> x.equals(x) should return true. * It is symmetric: for any instances x
>> and y of type Any, x.equals(y) should return true if and only if
>> y.equals(x) returns true. * It is transitive: for any instances x, y,
>> and z of type AnyRef if x.equals(y) returns true and y.equals(z)
>> returns true, then x.equals(z) should return true.
>>
>> Nice link to wikipedia there, except it isn't a link.
>>
>> 4. In JMockSugar. some of the methods take a Matcher, but it just says
>> Matcher. Well that's a org.hamcrest.Matcher, not a
>> org.scalatest.Matcher, and there's no way to tell from the
>> documentation. Example:
>>
>> http://www.artima.com/scaladocprobs/org/scalatest/mock/JMockExpectations...
>>
>> So probably there's a general problem with figuring out when to show a
>> fully qualified name and when not to.
>>
>> 5. I have carat symbols (^) in the code examples on this page:
>>
>> http://www.artima.com/scaladocprobs/org/scalatest/verb/CanVerb.html
>>
>> But they are just dropped from the output. I use them to point to
>> things all over the place. You can see the same thing here:
>>
>> http://www.artima.com/scaladocprobs/org/scalatest/matchers/Matchers$ResultOfNotWordForTraversable.html
>>
>
> Thank you for reporting. I'll see these problems.
>
>> I've gotten the vibe from EPFL that something like documentation is
>> very low priority. I understand they aren't as important as parallel
>> collecitons. But all these problems made ScalaTest much harder to use
>> since 2.8, and I think the state of Scaladoc in general reflects badly
>> on Scala itself. We'll submit more bugs tomorrow, and I hope you can
>> fix them  in 2.9.0, because i don't think they'll take long to fix and
>> they are in a tool off to the side.
>
> I can't feel the vibe. Probably, Switzerland is too far from Japan :)
>
> Regards,
>
> --
> Kato Kazuyoshi
>

Hi Bill,

I've checked the issue but I can't reproduce on my environment.

On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>
> Another thing I did in ScalaTest 1.3 was replace a few parts of the
> CSS file generated by ScalaDoc to try and improve the readability and
> fix issues I could fix. I increased the distance between paragraphs
> for example. I think I had to make a change to make strong actually
> show up as bold, and to turn off an underline on things.
> I also changed to a serif font to better distinguish the difference
> between text and code font, but that kind of thing I don't mind doing
> myself. I'll try and dig up what changes I made and submit that as a
> suggestion as well. If I had more time I'd pitch in to help with
> ScalaDoc, but unfortunately I just haven't been able to find the time
> to do that this year.
>

Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
don't have "display: none" on #comment.

#comment {
display:none;
padding-right: 8px;
padding-left: 8px;
}

Regards,

Hi Kato,

Thanks. I'll check into that. I had replaced the css file quite a
while back to try and work around issues. It is possible it was
updated since then.

Bill

On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
wrote:
> Hi Bill,
>
> I've checked the issue but I can't reproduce on my environment.
>
> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>
>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>> CSS file generated by ScalaDoc to try and improve the readability and
>> fix issues I could fix. I increased the distance between paragraphs
>> for example. I think I had to make a change to make strong actually
>> show up as bold, and to turn off an underline on things.
>> I also changed to a serif font to better distinguish the difference
>> between text and code font, but that kind of thing I don't mind doing
>> myself. I'll try and dig up what changes I made and submit that as a
>> suggestion as well. If I had more time I'd pitch in to help with
>> ScalaDoc, but unfortunately I just haven't been able to find the time
>> to do that this year.
>>
>
> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
> don't have "display: none" on #comment.
>
> #comment {
>  display:none;
>  padding-right: 8px;
>  padding-left: 8px;
> }
>
> Regards,
>
> --
> Kato Kazuyoshi
>

Hi Kato,

Just as a test I hand edited the template.css on the server. It now
has the display:none in it and I don't see the problem anymore. So I
think that was fixed and I just wasn't seeing it. Just to make sure I
was not getting a cached css file I made a copy here:

http://www.artima.com/xxx/scaladocprobs/

To be clear, the one I'm talking about is the one whereby the main doc
comment is repeated twice above the class or trait. The first line of
each method comment is still repeated. I looked at the 2.8
template.css file and sure enough that line isn't there:

#comment {
padding-right: 8px;
padding-left: 8px;
}

So I was using an outdated starting point. I.e., that was a bug in my
attempt to workaround other bugs. Thanks for finding the problem, and
sorry to waste your time on that one.

We just finished submitting bug reports to trak for the other issues I
noticed yesterday. They are:

#4356: — shows up in the output rather than being used as an
HTML entity. An example is here in the description (search for 8212)

#4357: “ and ” have the same problem. An example is on
this page (search for 8221):

#4358: i.e. causes everything after the i. in the same
paragraph to be dropped, and the rest of the entire page to show up in
italics. An example is on the call method documentation in the
description

#4359: eq method and equals method have markup

#4360: general problem with figuring out when to show a fully
qualified name and when not to

#4361: carat symbols (^) in the code examples are just dropped from
the output. They are used to point to things all over the place.

Thanks.

Bill

On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
wrote:
> Hi Bill,
>
> I've checked the issue but I can't reproduce on my environment.
>
> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>
>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>> CSS file generated by ScalaDoc to try and improve the readability and
>> fix issues I could fix. I increased the distance between paragraphs
>> for example. I think I had to make a change to make strong actually
>> show up as bold, and to turn off an underline on things.
>> I also changed to a serif font to better distinguish the difference
>> between text and code font, but that kind of thing I don't mind doing
>> myself. I'll try and dig up what changes I made and submit that as a
>> suggestion as well. If I had more time I'd pitch in to help with
>> ScalaDoc, but unfortunately I just haven't been able to find the time
>> to do that this year.
>>
>
> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
> don't have "display: none" on #comment.
>
> #comment {
>  display:none;
>  padding-right: 8px;
>  padding-left: 8px;
> }
>
> Regards,
>
> --
> Kato Kazuyoshi
>

On 3/18/11 4:52 PM, Bill Venners wrote:
> I got a stack trace when compiling under the latest 2.9.0-snapshot.
> I'll try going back to an older 2.9. In case it is useful to people,
> I've attached the stack trace below. Scala definitely has the most
> impressive stack traces I've seen.

[snip 1100 line stack trace]

I don't even see the code. All I see is blonde, brunette, red-head.

Here's a patch which will get you compiling again.

diff --git
a/src/test/scala/org/scalatest/BeforeAndAfterFunctionsSuite.scala
b/src/test/scala/org/scalatest/BeforeAndAfterFunctionsSuite.scala
index 7cbe9ad..1204642 100644

On 3/18/11 6:04 PM, Paul Phillips wrote:
> I don't even see the code. All I see is blonde, brunette, red-head.

Here's the facebook page for that particular blonde.

https://lampsvn.epfl.ch/trac/scala/ticket/4363

Hi Kato,

I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
attempting to compile the tests. (Even with Paul's patch I still got
the same stack trace. I'm probably doing the same thing elsewhere in
the tests.) I put up what it looks like with the normal css file here:

http://www.artima.com/scaladocprobs2/

I went through and verified that all the bugs we submitted to trak
today exist when using the normal css file.

To get a feel for the kind of changes I would suggest we do to the css
file, compare:

http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html

with:

http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html

I tried and it does seem to work now. That bug report was
closed already, but I wanted to check it. So at this point the main
thing I'd suggest is we put a bit more space between paragraphs, and
likely a bit more space between the lines. You could also consider
using a serif font. Tomorrow I'll try and figure out what amounts I
used in my css file. It isn't a simple diff anymore because your file
has changed so much since I forked it, and I don't have the one I
forked it from. Anyway, I should be able to make some concrete
suggestions for that tomorrow.

Thanks.

Bill

On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
wrote:
> Hi Bill,
>
> I've checked the issue but I can't reproduce on my environment.
>
> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>
>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>> CSS file generated by ScalaDoc to try and improve the readability and
>> fix issues I could fix. I increased the distance between paragraphs
>> for example. I think I had to make a change to make strong actually
>> show up as bold, and to turn off an underline on things.
>> I also changed to a serif font to better distinguish the difference
>> between text and code font, but that kind of thing I don't mind doing
>> myself. I'll try and dig up what changes I made and submit that as a
>> suggestion as well. If I had more time I'd pitch in to help with
>> ScalaDoc, but unfortunately I just haven't been able to find the time
>> to do that this year.
>>
>
> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
> don't have "display: none" on #comment.
>
> #comment {
>  display:none;
>  padding-right: 8px;
>  padding-left: 8px;
> }
>
> Regards,
>
> --
> Kato Kazuyoshi
>

On 3/18/11 8:08 PM, Bill Venners wrote:
> Hi Kato,
>
> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
> attempting to compile the tests. (Even with Paul's patch I still got
> the same stack trace. I'm probably doing the same thing elsewhere in
> the tests.)

Yeah, I'm positive that's the problem but I stopped when I'd gotten that
file to compile in isolation. I see now you have many uses of it. You
might want to take the opportunity to move your traits to the highest
level which makes sense. Defining traits inside closures when it's not
necessary is just asking for (and receiving) trouble.

Hello,

I'm no Scala committer, so I don't know if it is really ok for me to
post on this list, but I read the conversation and was reminded of the
shortcomings of the current Scaladoc layout.

Perhaps it's just me, but I find the current layout very hard to parse
visually, especially the lists of members. All the grey and white
alternating is more distracting that helping to bring structure to the
layout, IMHO. Also, there is generally a lack of padding, making
everything look very cramped and tangled up.

I would like to suggest the following changes to the CSS, which I
threw together in a quick Firebug session. It's just two added lines
and one removed line:

div.members > ol > li {
display: block; /* unchanged */
border-bottom: 1px solid black; /* new */
padding: 5px 0; /* new */
}

.signature {
/* removed background-color, everything else is unchanged */
clear: both;
display: block;
font-family: monospace;
font-size: 10pt;
padding: 3px;
}

If you use something like Firebug it takes only a minute to try it. I
would be happy to see changes like this make its way into the official
Scaladoc. Also, I would like add additional padding to various places,
to make the layout less cramped. But that is less of an issue compared
to the member lists.

Regards,
Ruediger Keller

2011/3/19 Bill Venners :
> Hi Kato,
>
> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
> attempting to compile the tests. (Even with Paul's patch I still got
> the same stack trace. I'm probably doing the same thing elsewhere in
> the tests.) I put up what it looks like with the normal css file here:
>
> http://www.artima.com/scaladocprobs2/
>
> I went through and verified that all the bugs we submitted to trak
> today exist when using the normal css file.
>
> To get a feel for the kind of changes I would suggest we do to the css
> file, compare:
>
> http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html
>
> with:
>
> http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html
>
> I tried and it does seem to work now. That bug report was
> closed already, but I wanted to check it. So at this point the main
> thing I'd suggest is we put a bit more space between paragraphs, and
> likely a bit more space between the lines. You could also consider
> using a serif font. Tomorrow I'll try and figure out what amounts I
> used in my css file. It isn't a simple diff anymore because your file
> has changed so much since I forked it, and I don't have the one I
> forked it from. Anyway, I should be able to make some concrete
> suggestions for that tomorrow.
>
> Thanks.
>
> Bill
>
> On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
> wrote:
>> Hi Bill,
>>
>> I've checked the issue but I can't reproduce on my environment.
>>
>> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>>
>>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>>> CSS file generated by ScalaDoc to try and improve the readability and
>>> fix issues I could fix. I increased the distance between paragraphs
>>> for example. I think I had to make a change to make strong actually
>>> show up as bold, and to turn off an underline on things.
>>> I also changed to a serif font to better distinguish the difference
>>> between text and code font, but that kind of thing I don't mind doing
>>> myself. I'll try and dig up what changes I made and submit that as a
>>> suggestion as well. If I had more time I'd pitch in to help with
>>> ScalaDoc, but unfortunately I just haven't been able to find the time
>>> to do that this year.
>>>
>>
>> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
>> don't have "display: none" on #comment.
>>
>> #comment {
>>  display:none;
>>  padding-right: 8px;
>>  padding-left: 8px;
>> }
>>
>> Regards,
>>
>> --
>> Kato Kazuyoshi
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

Hi Bill,

On Sat, Mar 19, 2011 at 9:23 AM, Bill Venners wrote:
>
> #4356: — shows up in the output rather than being used as an
> HTML entity. An example is here in the description (search for 8212)
>
> #4357: “ and ” have the same problem. An example is on
> this page (search for 8221):
>
> #4358: i.e. causes everything after the i. in the same
> paragraph to be dropped, and the rest of the entire page to show up in
> italics. An example is on the call method documentation in the
> description
>
> #4359: eq method and equals method have markup
>
> #4360: general problem with figuring out when to show a fully
> qualified name and when not to
>
> #4361: carat symbols (^) in the code examples are just dropped from
> the output. They are used to point to things all over the place.
>

I've fixed #4361 now. Please try SVN trunk again.

To: Other Scala committers

I have a commit rights on src/compiler/scala/tools/nsc/doc. But I want
to commit under src/compiler/scala/tools/nsc (SR-683) and
test/scaladoc.
How to get a commit bit on these directories?

Regards,

On 19/03/2011 13:23, Kato Kazuyoshi wrote:
> To: Other Scala committers
>
> I have a commit rights on src/compiler/scala/tools/nsc/doc. But I want
> to commit under src/compiler/scala/tools/nsc (SR-683) and
> test/scaladoc.
> How to get a commit bit on these directories?
>

Hello Kato,

I will forward your request to our sysadmin; you should get access on
Monday.

Toni

--
Antonio Cunei
Scala Team, EPFL

On Saturday March 19 2011, Rüdiger Keller wrote:
> Hello,
>
> ...
>
> div.members > ol > li {
> display: block; /* unchanged */
> border-bottom: 1px solid black; /* new */
> padding: 5px 0; /* new */
> }
>
> .signature {
> /* removed background-color, everything else is unchanged */
> clear: both;
> display: block;
> font-family: monospace;
> font-size: 10pt;
> padding: 3px;
> }

And let us note that the foregoing illustrates the proper way to use
colons. _No space on their left_, one on their right.

PLEASE!

> ...
>
> Regards,
> Ruediger Keller

Randall Schulz

Hi Paul,

On Fri, Mar 18, 2011 at 8:45 PM, Paul Phillips wrote:
> On 3/18/11 8:08 PM, Bill Venners wrote:
>>
>> Hi Kato,
>>
>> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
>> attempting to compile the tests. (Even with Paul's patch I still got
>> the same stack trace. I'm probably doing the same thing elsewhere in
>> the tests.)
>
> Yeah, I'm positive that's the problem but I stopped when I'd gotten that
> file to compile in isolation.  I see now you have many uses of it.  You
> might want to take the opportunity to move your traits to the highest level
> which makes sense.  Defining traits inside closures when it's not necessary
> is just asking for (and receiving) trouble.
>
In that one class you submitted a patch for, there were really two
different FunkySuite's, one that overrode run and another that
overrode runTests. Each was duplicated twice. It would be an
improvement to factor those out so they are shared and not duplicated.
(Each would be shared by two tests.) But in general, shouldn't it be
best practice to define any class or trait at whatever level makes
sense for it? In tests I think it will be common to want to define a
few classes and traits right where they are used, inside the test
itself, which is often a closure. That way they are only visible where
they are used. By defining them only up to the level they are needed,
it makes the intent more obvious--that it is only used in that scope.
What kind of trouble might that cause?

Bill

On 3/19/11 11:12 AM, Bill Venners wrote:
> But in general, shouldn't it be
> best practice to define any class or trait at whatever level makes
> sense for it? In tests I think it will be common to want to define a
> few classes and traits right where they are used, inside the test
> itself, which is often a closure. That way they are only visible where
> they are used. By defining them only up to the level they are needed,
> it makes the intent more obvious--that it is only used in that scope.
> What kind of trouble might that cause?

I'm just describing the reality of the implementation. It wasn't an
abstract idea about software engineering, it was an empirically proven
observation.

Hi Kato,

Thanks. I'll try this when the next 2.9.0-SNAPSHOT rolls around on the
guitar. I'm assuming the snapshot is being deployed automatically off
of the nightly build? Is that correct?

I'll also try building it from SVN, which I haven't ever tried before.

Bill

On Sat, Mar 19, 2011 at 5:23 AM, Kato Kazuyoshi
wrote:
> Hi Bill,
>
> On Sat, Mar 19, 2011 at 9:23 AM, Bill Venners wrote:
>>
>> #4356: — shows up in the output rather than being used as an
>> HTML entity. An example is here in the description (search for 8212)
>>
>> #4357: “ and ” have the same problem. An example is on
>> this page (search for 8221):
>>
>> #4358: i.e. causes everything after the i. in the same
>> paragraph to be dropped, and the rest of the entire page to show up in
>> italics. An example is on the call method documentation in the
>> description
>>
>> #4359: eq method and equals method have markup
>>
>> #4360: general problem with figuring out when to show a fully
>> qualified name and when not to
>>
>> #4361: carat symbols (^) in the code examples are just dropped from
>> the output. They are used to point to things all over the place.
>>
>
> I've fixed #4361 now. Please try SVN trunk again.
>
> To: Other Scala committers
>
> I have a commit rights on src/compiler/scala/tools/nsc/doc. But I want
> to commit under src/compiler/scala/tools/nsc (SR-683) and
> test/scaladoc.
> How to get a commit bit on these directories?
>
> Regards,
>
> --
> Kato Kazuyoshi
>

Hi Paul,

On Sat, Mar 19, 2011 at 11:19 AM, Paul Phillips wrote:
> On 3/19/11 11:12 AM, Bill Venners wrote:
>>
>> But in general, shouldn't it be
>> best practice to define any class or trait at whatever level makes
>> sense for it? In tests I think it will be common to want to define a
>> few classes and traits right where they are used, inside the test
>> itself, which is often a closure. That way they are only visible where
>> they are used. By defining them only up to the level they are needed,
>> it makes the intent more obvious--that it is only used in that scope.
>> What kind of trouble might that cause?
>
> I'm just describing the reality of the implementation.  It wasn't an
> abstract idea about software engineering, it was an empirically proven
> observation.
>
OK. Maybe it's good that I have done it then, so there's some code
that flags problems if they arise. One of the things I think is nice
about Scala is the nesting rules are very general. You are allowed to
put objects inside of classes inside of traits inside of classes
inside of methods inside of closures inside of objects inside of
traits, etc. Scoping works as it looks like it would work. At least it
is defined to work the way it looks like it would work. If you allow
people to do something like that, then someone somewhere is bound to
do it, so it does need to compile.

Bill
----
Bill Venners
Artima, Inc.
http://www.artima.com

Hi All,

I put up a version of ScalaTest's Scaladoc with Rüdiger's suggested
changes to the CSS file. You can compare the output of the original:

http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html

With what it looks like with your suggested changes:

http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html

If you click on Any and AnyRef you'll get more methods to see how it
looks. I think I like the alternating gray and white better than the
lines, but agree that adding a bit more margin above and below each
entry in the list is an improvement. I'll work on a suggested set of
changes to the css file right now and point you to it once I'm done.

Thanks.

Bill

On Sat, Mar 19, 2011 at 2:48 AM, Rüdiger Keller
wrote:
> Hello,
>
> I'm no Scala committer, so I don't know if it is really ok for me to
> post on this list, but I read the conversation and was reminded of the
> shortcomings of the current Scaladoc layout.
>
> Perhaps it's just me, but I find the current layout very hard to parse
> visually, especially the lists of members. All the grey and white
> alternating is more distracting that helping to bring structure to the
> layout, IMHO. Also, there is generally a lack of padding, making
> everything look very cramped and tangled up.
>
> I would like to suggest the following changes to the CSS, which I
> threw together in a quick Firebug session. It's just two added lines
> and one removed line:
>
> div.members > ol > li {
>  display: block; /* unchanged */
>  border-bottom: 1px solid black; /* new */
>  padding: 5px 0; /* new */
> }
>
> .signature {
>  /* removed background-color, everything else is unchanged */
>  clear: both;
>  display: block;
>  font-family: monospace;
>  font-size: 10pt;
>  padding: 3px;
> }
>
> If you use something like Firebug it takes only a minute to try it. I
> would be happy to see changes like this make its way into the official
> Scaladoc. Also, I would like add additional padding to various places,
> to make the layout less cramped. But that is less of an issue compared
> to the member lists.
>
> Regards,
> Ruediger Keller
>
>
>
> 2011/3/19 Bill Venners :
>> Hi Kato,
>>
>> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
>> attempting to compile the tests. (Even with Paul's patch I still got
>> the same stack trace. I'm probably doing the same thing elsewhere in
>> the tests.) I put up what it looks like with the normal css file here:
>>
>> http://www.artima.com/scaladocprobs2/
>>
>> I went through and verified that all the bugs we submitted to trak
>> today exist when using the normal css file.
>>
>> To get a feel for the kind of changes I would suggest we do to the css
>> file, compare:
>>
>> http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html
>>
>> with:
>>
>> http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html
>>
>> I tried and it does seem to work now. That bug report was
>> closed already, but I wanted to check it. So at this point the main
>> thing I'd suggest is we put a bit more space between paragraphs, and
>> likely a bit more space between the lines. You could also consider
>> using a serif font. Tomorrow I'll try and figure out what amounts I
>> used in my css file. It isn't a simple diff anymore because your file
>> has changed so much since I forked it, and I don't have the one I
>> forked it from. Anyway, I should be able to make some concrete
>> suggestions for that tomorrow.
>>
>> Thanks.
>>
>> Bill
>>
>> On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
>> wrote:
>>> Hi Bill,
>>>
>>> I've checked the issue but I can't reproduce on my environment.
>>>
>>> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>>>
>>>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>>>> CSS file generated by ScalaDoc to try and improve the readability and
>>>> fix issues I could fix. I increased the distance between paragraphs
>>>> for example. I think I had to make a change to make strong actually
>>>> show up as bold, and to turn off an underline on things.
>>>> I also changed to a serif font to better distinguish the difference
>>>> between text and code font, but that kind of thing I don't mind doing
>>>> myself. I'll try and dig up what changes I made and submit that as a
>>>> suggestion as well. If I had more time I'd pitch in to help with
>>>> ScalaDoc, but unfortunately I just haven't been able to find the time
>>>> to do that this year.
>>>>
>>>
>>> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
>>> don't have "display: none" on #comment.
>>>
>>> #comment {
>>>  display:none;
>>>  padding-right: 8px;
>>>  padding-left: 8px;
>>> }
>>>
>>> Regards,
>>>
>>> --
>>> Kato Kazuyoshi
>>>
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>>
>

Hi All, Sorry to not have noticed these earlier, but I have observed some other issues this morning, which I would call bugs, but don't think all need to be fixed necessarily by 2.9.0. One is that when I clicked on Any and AnyRef, sometimes there is blocks of gray. I.e., it doesn't always alternate between gray and white. For a specific example, on this page: http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html If I click on Hide All, then AnyRef, the !=, ##, $asInstanceOf, $isInstanceOf methods all show up together with a gray background. And another bug is that $asInstanceOf and $isInstanceOf should show up as asInstanceOf and isInstanceOf, because that's what people write and read in the code. Another one is that often these methods from Scala show up without any documentation. That makes the documentation look incomplete. This is true of the !=, ##, $asInstanceOf, $isInstanceOf methods I mentioned above, but also true of methods like canEqual, productArity, etc., that get generated for case classes. Would be nice to generate documentation for those compiler-generated methods in Scaladoc. An example is here: http://www.artima.com/sdp/original/org/scalatest/events/IndentedText.html We'll submit these as three more bugs in Trak, but again I think these could wait until after 2.9.0. One new one that I hope can be fixed in 2.9.0, because it shows up on a bunch of pages of ScalaTest's documentation, is that close strong tags are being dropped if they surround the entire comment for a method. Take a look here: http://www.artima.com/sdp/original/org/scalatest/TestFailedException.html The failedTestCodeFileNameAndLineNumberString is deprecated, and it has the doc comment: /** * failedTestCodeFileNameAndLineNumberString has been deprecated and will be removed in a future version of * ScalaTest. Please call failedCodeFileNameAndLineNumberString instead. */ @deprecated // deprecated in 1.0, remove in 1.4 val failedTestCodeFileNameAndLineNumberString: Option[String] = failedCodeFileNameAndLineNumberString The Scaladoc output is:

failedTestCodeFileNameAndLineNumberString has been deprecated and will be removed in a future version of ScalaTest.

failedTestCodeFileNameAndLineNumberString has been deprecated and will be removed in a future version of ScalaTest. Please call failedCodeFileNameAndLineNumberString instead.

So the shows up in the fullcomment, but not the shortcomment. That makes the rest of the method list comments all appear in bold. This happens pretty much on any ScalaTest trait or class that has something deprecated in it, which is a lot of things. It also screws up the JavaScript for the method with the problem, because if you click on the method, it hides the short comment, doesn't show the full comment, and then no matter how much mad clicking you do on that method thereafter, it won't show either the full or short comment. By the way, this also happens with the i.e. problem that we intended to already submit as a bug report, but I can't seem to find it. I'll check with Darlene. Maybe we forgot. But with the original CSS file, the doc comment is truncated when it hits i.e.. This shows up in the call method of EasyMockSugar: http://www.artima.com/sdp/original/org/scalatest/mock/EasyMockSugar.html When you click on that method, it hides the short comment, doesn't show the full comment, and no matter how may times you click on it anymore, you get nothing. These latter ones that eat documentation I think should be fixed in 2.9.0. I'll make sure we have all these submitted into Trak as soon as possible. Thanks. Bill ---- Bill Venners Artima, Inc. http://www.artima.com

Nice to see that someone looked at my suggestions. I have to admit
they aren't very refined, but I could create a more refined version if
there is demand for it.

Also, in my opinion the method parameters and attributes at the bottom
of method docs need some love. The spacings are irregular and the
parameter names aren't aligned with the parameter descriptions.

Should I post some more suggestions?

Regards,
Rüdiger

2011/3/19 Bill Venners :
> Hi All,
>
> I put up a version of ScalaTest's Scaladoc with Rüdiger's suggested
> changes to the CSS file. You can compare the output of the original:
>
> http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html
>
> With what it looks like with your suggested changes:
>
> http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html
>
> If you click on Any and AnyRef you'll get more methods to see how it
> looks. I think I like the alternating gray and white better than the
> lines, but agree that adding a bit more margin above and below each
> entry in the list is an improvement. I'll work on a suggested set of
> changes to the css file right now and point you to it once I'm done.
>
> Thanks.
>
> Bill
>
> On Sat, Mar 19, 2011 at 2:48 AM, Rüdiger Keller
> wrote:
>> Hello,
>>
>> I'm no Scala committer, so I don't know if it is really ok for me to
>> post on this list, but I read the conversation and was reminded of the
>> shortcomings of the current Scaladoc layout.
>>
>> Perhaps it's just me, but I find the current layout very hard to parse
>> visually, especially the lists of members. All the grey and white
>> alternating is more distracting that helping to bring structure to the
>> layout, IMHO. Also, there is generally a lack of padding, making
>> everything look very cramped and tangled up.
>>
>> I would like to suggest the following changes to the CSS, which I
>> threw together in a quick Firebug session. It's just two added lines
>> and one removed line:
>>
>> div.members > ol > li {
>>  display: block; /* unchanged */
>>  border-bottom: 1px solid black; /* new */
>>  padding: 5px 0; /* new */
>> }
>>
>> .signature {
>>  /* removed background-color, everything else is unchanged */
>>  clear: both;
>>  display: block;
>>  font-family: monospace;
>>  font-size: 10pt;
>>  padding: 3px;
>> }
>>
>> If you use something like Firebug it takes only a minute to try it. I
>> would be happy to see changes like this make its way into the official
>> Scaladoc. Also, I would like add additional padding to various places,
>> to make the layout less cramped. But that is less of an issue compared
>> to the member lists.
>>
>> Regards,
>> Ruediger Keller
>>
>>
>>
>> 2011/3/19 Bill Venners :
>>> Hi Kato,
>>>
>>> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
>>> attempting to compile the tests. (Even with Paul's patch I still got
>>> the same stack trace. I'm probably doing the same thing elsewhere in
>>> the tests.) I put up what it looks like with the normal css file here:
>>>
>>> http://www.artima.com/scaladocprobs2/
>>>
>>> I went through and verified that all the bugs we submitted to trak
>>> today exist when using the normal css file.
>>>
>>> To get a feel for the kind of changes I would suggest we do to the css
>>> file, compare:
>>>
>>> http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html
>>>
>>> with:
>>>
>>> http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html
>>>
>>> I tried and it does seem to work now. That bug report was
>>> closed already, but I wanted to check it. So at this point the main
>>> thing I'd suggest is we put a bit more space between paragraphs, and
>>> likely a bit more space between the lines. You could also consider
>>> using a serif font. Tomorrow I'll try and figure out what amounts I
>>> used in my css file. It isn't a simple diff anymore because your file
>>> has changed so much since I forked it, and I don't have the one I
>>> forked it from. Anyway, I should be able to make some concrete
>>> suggestions for that tomorrow.
>>>
>>> Thanks.
>>>
>>> Bill
>>>
>>> On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
>>> wrote:
>>>> Hi Bill,
>>>>
>>>> I've checked the issue but I can't reproduce on my environment.
>>>>
>>>> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>>>>
>>>>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>>>>> CSS file generated by ScalaDoc to try and improve the readability and
>>>>> fix issues I could fix. I increased the distance between paragraphs
>>>>> for example. I think I had to make a change to make strong actually
>>>>> show up as bold, and to turn off an underline on things.
>>>>> I also changed to a serif font to better distinguish the difference
>>>>> between text and code font, but that kind of thing I don't mind doing
>>>>> myself. I'll try and dig up what changes I made and submit that as a
>>>>> suggestion as well. If I had more time I'd pitch in to help with
>>>>> ScalaDoc, but unfortunately I just haven't been able to find the time
>>>>> to do that this year.
>>>>>
>>>>
>>>> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
>>>> don't have "display: none" on #comment.
>>>>
>>>> #comment {
>>>>  display:none;
>>>>  padding-right: 8px;
>>>>  padding-left: 8px;
>>>> }
>>>>
>>>> Regards,
>>>>
>>>> --
>>>> Kato Kazuyoshi
>>>>
>>>
>>>
>>>
>>> --
>>> Bill Venners
>>> Artima, Inc.
>>> http://www.artima.com
>>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

Hi All,

I've came up with some suggested changes to the template.css file.
Here's the before:

http://www.artima.com/sdp/original/org/scalatest/Suite.html

And here's the after:

http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html

The differences are:

I changed the line height from 1 to 1.1. This little tweak makes the
paragraphs easier to read in my opinion. The lines are currently
sitting too much right on top of each other.

I increases the margin around paragraphs in comments by quite a bit,
from 0.4em to 0.9em. The paragraphs were also very close together,
which made it hard to visually separate them.

I increased the padding for short comments from 0 to 2px to add just a
tad of space there. (As Ruediger Keller pointed out in his earlier,
they were also squished together.)

And what's a bit wierd is I decreased the padding for signatures from
3px to 2px. This made it look more uniform to me once the short
comment had a 2px padding.

Diff is:

[sites@artima01 sdp]$ diff original/lib/template.css suggestion/lib/template.css
20c20
< line-height: 1;
---
> line-height: 1.1;
172c172
< padding: 3px;
---
> padding: 2px;
234,235c234,235
< margin-bottom: 0.4em;
< margin-top: 0.4em;
---
> margin-bottom: 0.9em;
> margin-top: 0.9em;
362c362
< padding: 0;
---
> padding: 2px;

This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
haven't checked out the trunk yet. I'll do that later today. Let me
know if things have changed too much since I grabbed the template.css
file that you'd prefer I give you a diff off of trunk.

I tested this in Safari and Firefox on the Mac and Explorer and
Firefox on Windows. Would be good to have others look at it in other
browsers on other platforms. One thing I did play with is increasing
the font size, becuase 10pt looks very small on Safari on the Mac. But
that made fonts look uglier in the other browsers, so I dropped that.

I think these few changes to the template.css fie would go a long way
to making Scaladoc more readable.

Thanks.

Bill
----
Bill Venners
Artima, Inc.
http://www.artima.com

I like the suggested changes. Although for methods, in the section for
the method parameters at the bottom, the parameter names are now even
less properly aligned with the parameter description to the right.
Nonetheless the changes are a net gain.

Regards,
Rüdiger

2011/3/19 Bill Venners :
> Hi All,
>
> I've came up with some suggested changes to the template.css file.
> Here's the before:
>
> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>
> And here's the after:
>
> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>
> The differences are:
>
> I changed the line height from 1 to 1.1. This little tweak makes the
> paragraphs easier to read in my opinion. The lines are currently
> sitting  too much right on top of each other.
>
> I increases the margin around paragraphs in comments by quite a bit,
> from 0.4em to 0.9em. The paragraphs were also very close together,
> which made it hard to visually separate them.
>
> I increased the padding for short comments from 0 to 2px to add just a
> tad of space there. (As Ruediger Keller pointed out in his earlier,
> they were also squished together.)
>
> And what's a bit wierd is I decreased the padding for signatures from
> 3px to 2px. This made it look more uniform to me once the short
> comment had a 2px padding.
>
> Diff is:
>
> [sites@artima01 sdp]$ diff original/lib/template.css suggestion/lib/template.css
> 20c20
> <   line-height: 1;
> ---
>>   line-height: 1.1;
> 172c172
> <   padding: 3px;
> ---
>>   padding: 2px;
> 234,235c234,235
> <       margin-bottom: 0.4em;
> <       margin-top: 0.4em;
> ---
>>       margin-bottom: 0.9em;
>>       margin-top: 0.9em;
> 362c362
> <   padding: 0;
> ---
>>   padding: 2px;
>
> This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
> haven't checked out the trunk yet. I'll do that later today. Let me
> know if things have changed too much since I grabbed the template.css
> file that you'd prefer I give you a diff off of trunk.
>
> I tested this in Safari and Firefox on the Mac and Explorer and
> Firefox on Windows. Would be good to have others look at it in other
> browsers on other platforms. One thing I did play with is increasing
> the font size, becuase 10pt looks very small on Safari on the Mac. But
> that made fonts look uglier in the other browsers, so I dropped that.
>
> I think these few changes to the template.css fie would go a long way
> to making Scaladoc more readable.
>
> Thanks.
>
> Bill
> ----
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

Rüdiger,

I'll be in charge of some of the Scaladoc tasks for the next few months, and I quite appreciate your suggestions and your new CSS layout (particularly as I'm still learning the intricacies of CSS). So, to answer your question--yes! We would love more suggestions, and refined a CSS if you have time. I think the visual design of Scaladoc is quite important, and I am quite happy to see so many contributions and comments from the community.

thanks,
Donna

On Mar 19, 2011, at 9:23 PM, Rüdiger Keller wrote:

> Nice to see that someone looked at my suggestions. I have to admit
> they aren't very refined, but I could create a more refined version if
> there is demand for it.
>
> Also, in my opinion the method parameters and attributes at the bottom
> of method docs need some love. The spacings are irregular and the
> parameter names aren't aligned with the parameter descriptions.
>
> Should I post some more suggestions?
>
> Regards,
> Rüdiger
>
>
> 2011/3/19 Bill Venners :
>> Hi All,
>>
>> I put up a version of ScalaTest's Scaladoc with Rüdiger's suggested
>> changes to the CSS file. You can compare the output of the original:
>>
>> http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html
>>
>> With what it looks like with your suggested changes:
>>
>> http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html
>>
>> If you click on Any and AnyRef you'll get more methods to see how it
>> looks. I think I like the alternating gray and white better than the
>> lines, but agree that adding a bit more margin above and below each
>> entry in the list is an improvement. I'll work on a suggested set of
>> changes to the css file right now and point you to it once I'm done.
>>
>> Thanks.
>>
>> Bill
>>
>> On Sat, Mar 19, 2011 at 2:48 AM, Rüdiger Keller
>> wrote:
>>> Hello,
>>>
>>> I'm no Scala committer, so I don't know if it is really ok for me to
>>> post on this list, but I read the conversation and was reminded of the
>>> shortcomings of the current Scaladoc layout.
>>>
>>> Perhaps it's just me, but I find the current layout very hard to parse
>>> visually, especially the lists of members. All the grey and white
>>> alternating is more distracting that helping to bring structure to the
>>> layout, IMHO. Also, there is generally a lack of padding, making
>>> everything look very cramped and tangled up.
>>>
>>> I would like to suggest the following changes to the CSS, which I
>>> threw together in a quick Firebug session. It's just two added lines
>>> and one removed line:
>>>
>>> div.members > ol > li {
>>> display: block; /* unchanged */
>>> border-bottom: 1px solid black; /* new */
>>> padding: 5px 0; /* new */
>>> }
>>>
>>> .signature {
>>> /* removed background-color, everything else is unchanged */
>>> clear: both;
>>> display: block;
>>> font-family: monospace;
>>> font-size: 10pt;
>>> padding: 3px;
>>> }
>>>
>>> If you use something like Firebug it takes only a minute to try it. I
>>> would be happy to see changes like this make its way into the official
>>> Scaladoc. Also, I would like add additional padding to various places,
>>> to make the layout less cramped. But that is less of an issue compared
>>> to the member lists.
>>>
>>> Regards,
>>> Ruediger Keller
>>>
>>>
>>>
>>> 2011/3/19 Bill Venners :
>>>> Hi Kato,
>>>>
>>>> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
>>>> attempting to compile the tests. (Even with Paul's patch I still got
>>>> the same stack trace. I'm probably doing the same thing elsewhere in
>>>> the tests.) I put up what it looks like with the normal css file here:
>>>>
>>>> http://www.artima.com/scaladocprobs2/
>>>>
>>>> I went through and verified that all the bugs we submitted to trak
>>>> today exist when using the normal css file.
>>>>
>>>> To get a feel for the kind of changes I would suggest we do to the css
>>>> file, compare:
>>>>
>>>> http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html
>>>>
>>>> with:
>>>>
>>>> http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html
>>>>
>>>> I tried and it does seem to work now. That bug report was
>>>> closed already, but I wanted to check it. So at this point the main
>>>> thing I'd suggest is we put a bit more space between paragraphs, and
>>>> likely a bit more space between the lines. You could also consider
>>>> using a serif font. Tomorrow I'll try and figure out what amounts I
>>>> used in my css file. It isn't a simple diff anymore because your file
>>>> has changed so much since I forked it, and I don't have the one I
>>>> forked it from. Anyway, I should be able to make some concrete
>>>> suggestions for that tomorrow.
>>>>
>>>> Thanks.
>>>>
>>>> Bill
>>>>
>>>> On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
>>>> wrote:
>>>>> Hi Bill,
>>>>>
>>>>> I've checked the issue but I can't reproduce on my environment.
>>>>>
>>>>> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>>>>>
>>>>>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>>>>>> CSS file generated by ScalaDoc to try and improve the readability and
>>>>>> fix issues I could fix. I increased the distance between paragraphs
>>>>>> for example. I think I had to make a change to make strong actually
>>>>>> show up as bold, and to turn off an underline on things.
>>>>>> I also changed to a serif font to better distinguish the difference
>>>>>> between text and code font, but that kind of thing I don't mind doing
>>>>>> myself. I'll try and dig up what changes I made and submit that as a
>>>>>> suggestion as well. If I had more time I'd pitch in to help with
>>>>>> ScalaDoc, but unfortunately I just haven't been able to find the time
>>>>>> to do that this year.
>>>>>>
>>>>>
>>>>> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
>>>>> don't have "display: none" on #comment.
>>>>>
>>>>> #comment {
>>>>> display:none;
>>>>> padding-right: 8px;
>>>>> padding-left: 8px;
>>>>> }
>>>>>
>>>>> Regards,
>>>>>
>>>>> --
>>>>> Kato Kazuyoshi
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Bill Venners
>>>> Artima, Inc.
>>>> http://www.artima.com
>>>>
>>>
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>>

Hi Rüdiger,

Can you elaborate on which section you are concerned about? Is it when
you click on a method name, and it pops out the long description
(which works really nicely now, by the way), the name of the param is
a bit higher than the description?

Bill

On Sat, Mar 19, 2011 at 3:10 PM, Ruediger Keller
wrote:
> I like the suggested changes. Although for methods, in the section for
> the method parameters at the bottom, the parameter names are now even
> less properly aligned with the parameter description to the right.
> Nonetheless the changes are a net gain.
>
> Regards,
> Rüdiger
>
>
> 2011/3/19 Bill Venners :
>> Hi All,
>>
>> I've came up with some suggested changes to the template.css file.
>> Here's the before:
>>
>> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>>
>> And here's the after:
>>
>> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>>
>> The differences are:
>>
>> I changed the line height from 1 to 1.1. This little tweak makes the
>> paragraphs easier to read in my opinion. The lines are currently
>> sitting  too much right on top of each other.
>>
>> I increases the margin around paragraphs in comments by quite a bit,
>> from 0.4em to 0.9em. The paragraphs were also very close together,
>> which made it hard to visually separate them.
>>
>> I increased the padding for short comments from 0 to 2px to add just a
>> tad of space there. (As Ruediger Keller pointed out in his earlier,
>> they were also squished together.)
>>
>> And what's a bit wierd is I decreased the padding for signatures from
>> 3px to 2px. This made it look more uniform to me once the short
>> comment had a 2px padding.
>>
>> Diff is:
>>
>> [sites@artima01 sdp]$ diff original/lib/template.css suggestion/lib/template.css
>> 20c20
>> <   line-height: 1;
>> ---
>>>   line-height: 1.1;
>> 172c172
>> <   padding: 3px;
>> ---
>>>   padding: 2px;
>> 234,235c234,235
>> <       margin-bottom: 0.4em;
>> <       margin-top: 0.4em;
>> ---
>>>       margin-bottom: 0.9em;
>>>       margin-top: 0.9em;
>> 362c362
>> <   padding: 0;
>> ---
>>>   padding: 2px;
>>
>> This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
>> haven't checked out the trunk yet. I'll do that later today. Let me
>> know if things have changed too much since I grabbed the template.css
>> file that you'd prefer I give you a diff off of trunk.
>>
>> I tested this in Safari and Firefox on the Mac and Explorer and
>> Firefox on Windows. Would be good to have others look at it in other
>> browsers on other platforms. One thing I did play with is increasing
>> the font size, becuase 10pt looks very small on Safari on the Mac. But
>> that made fonts look uglier in the other browsers, so I dropped that.
>>
>> I think these few changes to the template.css fie would go a long way
>> to making Scaladoc more readable.
>>
>> Thanks.
>>
>> Bill
>> ----
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>>
>

Hi Donna,

Nice to meet you. I was hoping to get some last minute suggestions
into Scaladoc for 2.9.0, but at this late point understand they'd need
to be quick to fix and low risk. After 2.9.0 more can be done. I have
been concerned about it more than others possibly because I really put
Scaladoc through its paces in ScalaTest documentation. I have
HTML-markup documentation, etc., for several classes and traits, and
that markup was broken badly in 2.8.0 in addition to the layout being
less readable than 2.7.7. It really made the tool harder to use for
ScalaTest users, and I had to spend time and money trying to work
around it. It is is much better shape now, and with a few more tweaks
and fixes will be even better. Hopefully we can squeeze a few more
improvements into 2.9.0.

Bill

On Sat, Mar 19, 2011 at 3:19 PM, Donna Malayeri wrote:
> Rüdiger,
>
> I'll be in charge of some of the Scaladoc tasks for the next few months, and I quite appreciate your suggestions and your new CSS layout (particularly as I'm still learning the intricacies of CSS). So, to answer your question--yes!  We would love more suggestions, and refined a CSS if you have time. I think the visual design of Scaladoc is quite important, and I am quite happy to see so many contributions and comments from the community.
>
> thanks,
> Donna
>
> On Mar 19, 2011, at 9:23 PM, Rüdiger Keller wrote:
>
>> Nice to see that someone looked at my suggestions. I have to admit
>> they aren't very refined, but I could create a more refined version if
>> there is demand for it.
>>
>> Also, in my opinion the method parameters and attributes at the bottom
>> of method docs need some love. The spacings are irregular and the
>> parameter names aren't aligned with the parameter descriptions.
>>
>> Should I post some more suggestions?
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/19 Bill Venners :
>>> Hi All,
>>>
>>> I put up a version of ScalaTest's Scaladoc with Rüdiger's suggested
>>> changes to the CSS file. You can compare the output of the original:
>>>
>>> http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html
>>>
>>> With what it looks like with your suggested changes:
>>>
>>> http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html
>>>
>>> If you click on Any and AnyRef you'll get more methods to see how it
>>> looks. I think I like the alternating gray and white better than the
>>> lines, but agree that adding a bit more margin above and below each
>>> entry in the list is an improvement. I'll work on a suggested set of
>>> changes to the css file right now and point you to it once I'm done.
>>>
>>> Thanks.
>>>
>>> Bill
>>>
>>> On Sat, Mar 19, 2011 at 2:48 AM, Rüdiger Keller
>>> wrote:
>>>> Hello,
>>>>
>>>> I'm no Scala committer, so I don't know if it is really ok for me to
>>>> post on this list, but I read the conversation and was reminded of the
>>>> shortcomings of the current Scaladoc layout.
>>>>
>>>> Perhaps it's just me, but I find the current layout very hard to parse
>>>> visually, especially the lists of members. All the grey and white
>>>> alternating is more distracting that helping to bring structure to the
>>>> layout, IMHO. Also, there is generally a lack of padding, making
>>>> everything look very cramped and tangled up.
>>>>
>>>> I would like to suggest the following changes to the CSS, which I
>>>> threw together in a quick Firebug session. It's just two added lines
>>>> and one removed line:
>>>>
>>>> div.members > ol > li {
>>>>  display: block; /* unchanged */
>>>>  border-bottom: 1px solid black; /* new */
>>>>  padding: 5px 0; /* new */
>>>> }
>>>>
>>>> .signature {
>>>>  /* removed background-color, everything else is unchanged */
>>>>  clear: both;
>>>>  display: block;
>>>>  font-family: monospace;
>>>>  font-size: 10pt;
>>>>  padding: 3px;
>>>> }
>>>>
>>>> If you use something like Firebug it takes only a minute to try it. I
>>>> would be happy to see changes like this make its way into the official
>>>> Scaladoc. Also, I would like add additional padding to various places,
>>>> to make the layout less cramped. But that is less of an issue compared
>>>> to the member lists.
>>>>
>>>> Regards,
>>>> Ruediger Keller
>>>>
>>>>
>>>>
>>>> 2011/3/19 Bill Venners :
>>>>> Hi Kato,
>>>>>
>>>>> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
>>>>> attempting to compile the tests. (Even with Paul's patch I still got
>>>>> the same stack trace. I'm probably doing the same thing elsewhere in
>>>>> the tests.) I put up what it looks like with the normal css file here:
>>>>>
>>>>> http://www.artima.com/scaladocprobs2/
>>>>>
>>>>> I went through and verified that all the bugs we submitted to trak
>>>>> today exist when using the normal css file.
>>>>>
>>>>> To get a feel for the kind of changes I would suggest we do to the css
>>>>> file, compare:
>>>>>
>>>>> http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html
>>>>>
>>>>> with:
>>>>>
>>>>> http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html
>>>>>
>>>>> I tried and it does seem to work now. That bug report was
>>>>> closed already, but I wanted to check it. So at this point the main
>>>>> thing I'd suggest is we put a bit more space between paragraphs, and
>>>>> likely a bit more space between the lines. You could also consider
>>>>> using a serif font. Tomorrow I'll try and figure out what amounts I
>>>>> used in my css file. It isn't a simple diff anymore because your file
>>>>> has changed so much since I forked it, and I don't have the one I
>>>>> forked it from. Anyway, I should be able to make some concrete
>>>>> suggestions for that tomorrow.
>>>>>
>>>>> Thanks.
>>>>>
>>>>> Bill
>>>>>
>>>>> On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
>>>>> wrote:
>>>>>> Hi Bill,
>>>>>>
>>>>>> I've checked the issue but I can't reproduce on my environment.
>>>>>>
>>>>>> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>>>>>>
>>>>>>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>>>>>>> CSS file generated by ScalaDoc to try and improve the readability and
>>>>>>> fix issues I could fix. I increased the distance between paragraphs
>>>>>>> for example. I think I had to make a change to make strong actually
>>>>>>> show up as bold, and to turn off an underline on things.
>>>>>>> I also changed to a serif font to better distinguish the difference
>>>>>>> between text and code font, but that kind of thing I don't mind doing
>>>>>>> myself. I'll try and dig up what changes I made and submit that as a
>>>>>>> suggestion as well. If I had more time I'd pitch in to help with
>>>>>>> ScalaDoc, but unfortunately I just haven't been able to find the time
>>>>>>> to do that this year.
>>>>>>>
>>>>>>
>>>>>> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
>>>>>> don't have "display: none" on #comment.
>>>>>>
>>>>>> #comment {
>>>>>>  display:none;
>>>>>>  padding-right: 8px;
>>>>>>  padding-left: 8px;
>>>>>> }
>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> --
>>>>>> Kato Kazuyoshi
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Bill Venners
>>>>> Artima, Inc.
>>>>> http://www.artima.com
>>>>>
>>>>
>>>
>>>
>>>
>>> --
>>> Bill Venners
>>> Artima, Inc.
>>> http://www.artima.com
>>>
>
>

On Sat, Mar 19, 2011 at 5:19 PM, Donna Malayeri <lindydonna@gmail.com> wrote:

Rüdiger,

I'll be in charge of some of the Scaladoc tasks for the next few months, and I quite appreciate your suggestions and your new CSS layout (particularly as I'm still learning the intricacies of CSS). So, to answer your question--yes!  We would love more suggestions, and refined a CSS if you have time. I think the visual design of Scaladoc is quite important, and I am quite happy to see so many contributions and comments from the community.

I know this is not helpful at all, but could something be done about the awful color scheme?

On 19/03/2011 19:26, Bill Venners wrote:
> Hi Kato,
>
> Thanks. I'll try this when the next 2.9.0-SNAPSHOT rolls around on the
> guitar. I'm assuming the snapshot is being deployed automatically off
> of the nightly build? Is that correct?
>

Bill,

Right now 2.9.0-SNAPSHOT is built from the 2.9.x branch, which is
updated manually and may be a few commits behind. However
2.10.0-SNAPSHOT at this time corresponds exactly to the nightly from trunk.

Toni

Hi Bill,

I'm answering your question from the other thread here.

> Can you elaborate on which section you are concerned about? Is it when
> you click on a method name, and it pops out the long description
> (which works really nicely now, by the way), the name of the param is
> a bit higher than the description?

Yes, that's exactly what I am referring to. The parameter descriptions
at the bottom of the expanded method descriptions. I think it would
look better if the parameter names were aligned with the first line of
description.

I will try to improve the layout a bit more and that is one of the
points on the list. If you don't mind I will use your suggestion as
the basis for my work.

@everyone: If someone has ideas for improvement, please speak up. I'm
no user interface designer, I just happen to know a little bit of CSS.
Also, I would like to hear how you like my initial proposal, where I
changed the style for the value members list. Bill was so kind to put
up a version of his ScalaTest Scaladocs with it:

Original:
http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html

My suggestions:
http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html

I think my suggestion can be improved further, but first I want to
know it it's worth the time. If everyone is in favor of the old style
with alternating grey and white, I will not pursue this approach.

Hmm, I just noticed it looks much better if the separating lines
aren't black but light gray. Perhaps I will first put up a further
improved version and then everyone can comment.

Regards,
Rüdiger

2011/3/19 Bill Venners :
> Hi Rüdiger,
>
> Can you elaborate on which section you are concerned about? Is it when
> you click on a method name, and it pops out the long description
> (which works really nicely now, by the way), the name of the param is
> a bit higher than the description?
>
> Bill
>
> On Sat, Mar 19, 2011 at 3:10 PM, Ruediger Keller
> wrote:
>> I like the suggested changes. Although for methods, in the section for
>> the method parameters at the bottom, the parameter names are now even
>> less properly aligned with the parameter description to the right.
>> Nonetheless the changes are a net gain.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/19 Bill Venners :
>>> Hi All,
>>>
>>> I've came up with some suggested changes to the template.css file.
>>> Here's the before:
>>>
>>> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>>>
>>> And here's the after:
>>>
>>> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>>>
>>> The differences are:
>>>
>>> I changed the line height from 1 to 1.1. This little tweak makes the
>>> paragraphs easier to read in my opinion. The lines are currently
>>> sitting too much right on top of each other.
>>>
>>> I increases the margin around paragraphs in comments by quite a bit,
>>> from 0.4em to 0.9em. The paragraphs were also very close together,
>>> which made it hard to visually separate them.
>>>
>>> I increased the padding for short comments from 0 to 2px to add just a
>>> tad of space there. (As Ruediger Keller pointed out in his earlier,
>>> they were also squished together.)
>>>
>>> And what's a bit wierd is I decreased the padding for signatures from
>>> 3px to 2px. This made it look more uniform to me once the short
>>> comment had a 2px padding.
>>>
>>> Diff is:
>>>
>>> [sites@artima01 sdp]$ diff original/lib/template.css suggestion/lib/template.css
>>> 20c20
>>> < line-height: 1;
>>> ---
>>>> line-height: 1.1;
>>> 172c172
>>> < padding: 3px;
>>> ---
>>>> padding: 2px;
>>> 234,235c234,235
>>> < margin-bottom: 0.4em;
>>> < margin-top: 0.4em;
>>> ---
>>>> margin-bottom: 0.9em;
>>>> margin-top: 0.9em;
>>> 362c362
>>> < padding: 0;
>>> ---
>>>> padding: 2px;
>>>
>>> This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
>>> haven't checked out the trunk yet. I'll do that later today. Let me
>>> know if things have changed too much since I grabbed the template.css
>>> file that you'd prefer I give you a diff off of trunk.
>>>
>>> I tested this in Safari and Firefox on the Mac and Explorer and
>>> Firefox on Windows. Would be good to have others look at it in other
>>> browsers on other platforms. One thing I did play with is increasing
>>> the font size, becuase 10pt looks very small on Safari on the Mac. But
>>> that made fonts look uglier in the other browsers, so I dropped that.
>>>
>>> I think these few changes to the template.css fie would go a long way
>>> to making Scaladoc more readable.
>>>
>>> Thanks.
>>>
>>> Bill
>>> ----
>>> Bill Venners
>>> Artima, Inc.
>>> http://www.artima.com
>>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

Well, one thing to be concerned about is that the grayed areas are clickable areas. With your suggestions, there's no indication at all of what is a clickable area. Something must be done about this.

On Sun, Mar 20, 2011 at 06:23, Ruediger Keller <ruediger.keller@rk42.de> wrote:

Hi Bill,

I'm answering your question from the other thread here.

> Can you elaborate on which section you are concerned about? Is it when
> you click on a method name, and it pops out the long description
> (which works really nicely now, by the way), the name of the param is
> a bit higher than the description?

Yes, that's exactly what I am referring to. The parameter descriptions
at the bottom of the expanded method descriptions. I think it would
look better if the parameter names were aligned with the first line of
description.

I will try to improve the layout a bit more and that is one of the
points on the list. If you don't mind I will use your suggestion as
the basis for my work.


@everyone: If someone has ideas for improvement, please speak up. I'm
no user interface designer, I just happen to know a little bit of CSS.
Also, I would like to hear how you like my initial proposal, where I
changed the style for the value members list. Bill was so kind to put
up a version of his ScalaTest Scaladocs with it:

Original:
http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html

My suggestions:
http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html


I think my suggestion can be improved further, but first I want to
know it it's worth the time. If everyone is in favor of the old style
with alternating grey and white, I will not pursue this approach.

Hmm, I just noticed it looks much better if the separating lines
aren't black but light gray. Perhaps I will first put up a further
improved version and then everyone can comment.

Regards,
Rüdiger


2011/3/19 Bill Venners <bill@artima.com>:
> Hi Rüdiger,
>
> Can you elaborate on which section you are concerned about? Is it when
> you click on a method name, and it pops out the long description
> (which works really nicely now, by the way), the name of the param is
> a bit higher than the description?
>
> Bill
>
> On Sat, Mar 19, 2011 at 3:10 PM, Ruediger Keller
> <ruediger.keller@rk42.de> wrote:
>> I like the suggested changes. Although for methods, in the section for
>> the method parameters at the bottom, the parameter names are now even
>> less properly aligned with the parameter description to the right.
>> Nonetheless the changes are a net gain.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/19 Bill Venners <bill@artima.com>:
>>> Hi All,
>>>
>>> I've came up with some suggested changes to the template.css file.
>>> Here's the before:
>>>
>>> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>>>
>>> And here's the after:
>>>
>>> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>>>
>>> The differences are:
>>>
>>> I changed the line height from 1 to 1.1. This little tweak makes the
>>> paragraphs easier to read in my opinion. The lines are currently
>>> sitting  too much right on top of each other.
>>>
>>> I increases the margin around paragraphs in comments by quite a bit,
>>> from 0.4em to 0.9em. The paragraphs were also very close together,
>>> which made it hard to visually separate them.
>>>
>>> I increased the padding for short comments from 0 to 2px to add just a
>>> tad of space there. (As Ruediger Keller pointed out in his earlier,
>>> they were also squished together.)
>>>
>>> And what's a bit wierd is I decreased the padding for signatures from
>>> 3px to 2px. This made it look more uniform to me once the short
>>> comment had a 2px padding.
>>>
>>> Diff is:
>>>
>>> [sites@artima01 sdp]$ diff original/lib/template.css suggestion/lib/template.css
>>> 20c20
>>> <   line-height: 1;
>>> ---
>>>>   line-height: 1.1;
>>> 172c172
>>> <   padding: 3px;
>>> ---
>>>>   padding: 2px;
>>> 234,235c234,235
>>> <       margin-bottom: 0.4em;
>>> <       margin-top: 0.4em;
>>> ---
>>>>       margin-bottom: 0.9em;
>>>>       margin-top: 0.9em;
>>> 362c362
>>> <   padding: 0;
>>> ---
>>>>   padding: 2px;
>>>
>>> This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
>>> haven't checked out the trunk yet. I'll do that later today. Let me
>>> know if things have changed too much since I grabbed the template.css
>>> file that you'd prefer I give you a diff off of trunk.
>>>
>>> I tested this in Safari and Firefox on the Mac and Explorer and
>>> Firefox on Windows. Would be good to have others look at it in other
>>> browsers on other platforms. One thing I did play with is increasing
>>> the font size, becuase 10pt looks very small on Safari on the Mac. But
>>> that made fonts look uglier in the other browsers, so I dropped that.
>>>
>>> I think these few changes to the template.css fie would go a long way
>>> to making Scaladoc more readable.
>>>
>>> Thanks.
>>>
>>> Bill
>>> ----
>>> Bill Venners
>>> Artima, Inc.
>>> http://www.artima.com
>>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

--
Daniel C. Sobral

I travel to the future all the time.

Well, I thought about that too. But frankly I'm not too concerned.

There are other clickable areas in the current scaladoc that aren't
highlighted at all. The text with white background below the gray
signatures, for example.

Also, since when is gray background an indication of "clickable"? For
me it's not. And for the current scaladoc it's also not. Because it's
not consistent about this. Some gray backgrounds are clickable, some
are not. Examples: the class signature at the top of the file,
instance constructors, type members.

But! If you have a good idea for a visual indication of
"clickability", I'm more than willing to try to implement it.

Perhaps the white backgrounds need some getting used to, but I'm sure
the gray ones also did. So please give them a try.

Also, if everyone insists that signatures must have gray backgrounds,
I will create a version with it, but in my opinion it's just visual
noise that impedes scanning of the page.

Regards,
Rüdiger

2011/3/20 Daniel Sobral :
> Well, one thing to be concerned about is that the grayed areas are clickable
> areas. With your suggestions, there's no indication at all of what is a
> clickable area. Something must be done about this.
>
> On Sun, Mar 20, 2011 at 06:23, Ruediger Keller
> wrote:
>>
>> Hi Bill,
>>
>> I'm answering your question from the other thread here.
>>
>> > Can you elaborate on which section you are concerned about? Is it when
>> > you click on a method name, and it pops out the long description
>> > (which works really nicely now, by the way), the name of the param is
>> > a bit higher than the description?
>>
>> Yes, that's exactly what I am referring to. The parameter descriptions
>> at the bottom of the expanded method descriptions. I think it would
>> look better if the parameter names were aligned with the first line of
>> description.
>>
>> I will try to improve the layout a bit more and that is one of the
>> points on the list. If you don't mind I will use your suggestion as
>> the basis for my work.
>>
>>
>> @everyone: If someone has ideas for improvement, please speak up. I'm
>> no user interface designer, I just happen to know a little bit of CSS.
>> Also, I would like to hear how you like my initial proposal, where I
>> changed the style for the value members list. Bill was so kind to put
>> up a version of his ScalaTest Scaladocs with it:
>>
>> Original:
>> http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html
>>
>> My suggestions:
>> http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html
>>
>>
>> I think my suggestion can be improved further, but first I want to
>> know it it's worth the time. If everyone is in favor of the old style
>> with alternating grey and white, I will not pursue this approach.
>>
>> Hmm, I just noticed it looks much better if the separating lines
>> aren't black but light gray. Perhaps I will first put up a further
>> improved version and then everyone can comment.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/19 Bill Venners :
>> > Hi Rüdiger,
>> >
>> > Can you elaborate on which section you are concerned about? Is it when
>> > you click on a method name, and it pops out the long description
>> > (which works really nicely now, by the way), the name of the param is
>> > a bit higher than the description?
>> >
>> > Bill
>> >
>> > On Sat, Mar 19, 2011 at 3:10 PM, Ruediger Keller
>> > wrote:
>> >> I like the suggested changes. Although for methods, in the section for
>> >> the method parameters at the bottom, the parameter names are now even
>> >> less properly aligned with the parameter description to the right.
>> >> Nonetheless the changes are a net gain.
>> >>
>> >> Regards,
>> >> Rüdiger
>> >>
>> >>
>> >> 2011/3/19 Bill Venners :
>> >>> Hi All,
>> >>>
>> >>> I've came up with some suggested changes to the template.css file.
>> >>> Here's the before:
>> >>>
>> >>> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>> >>>
>> >>> And here's the after:
>> >>>
>> >>> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>> >>>
>> >>> The differences are:
>> >>>
>> >>> I changed the line height from 1 to 1.1. This little tweak makes the
>> >>> paragraphs easier to read in my opinion. The lines are currently
>> >>> sitting  too much right on top of each other.
>> >>>
>> >>> I increases the margin around paragraphs in comments by quite a bit,
>> >>> from 0.4em to 0.9em. The paragraphs were also very close together,
>> >>> which made it hard to visually separate them.
>> >>>
>> >>> I increased the padding for short comments from 0 to 2px to add just a
>> >>> tad of space there. (As Ruediger Keller pointed out in his earlier,
>> >>> they were also squished together.)
>> >>>
>> >>> And what's a bit wierd is I decreased the padding for signatures from
>> >>> 3px to 2px. This made it look more uniform to me once the short
>> >>> comment had a 2px padding.
>> >>>
>> >>> Diff is:
>> >>>
>> >>> [sites@artima01 sdp]$ diff original/lib/template.css
>> >>> suggestion/lib/template.css
>> >>> 20c20
>> >>> <   line-height: 1;
>> >>> ---
>> >>>>   line-height: 1.1;
>> >>> 172c172
>> >>> <   padding: 3px;
>> >>> ---
>> >>>>   padding: 2px;
>> >>> 234,235c234,235
>> >>> <       margin-bottom: 0.4em;
>> >>> <       margin-top: 0.4em;
>> >>> ---
>> >>>>       margin-bottom: 0.9em;
>> >>>>       margin-top: 0.9em;
>> >>> 362c362
>> >>> <   padding: 0;
>> >>> ---
>> >>>>   padding: 2px;
>> >>>
>> >>> This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
>> >>> haven't checked out the trunk yet. I'll do that later today. Let me
>> >>> know if things have changed too much since I grabbed the template.css
>> >>> file that you'd prefer I give you a diff off of trunk.
>> >>>
>> >>> I tested this in Safari and Firefox on the Mac and Explorer and
>> >>> Firefox on Windows. Would be good to have others look at it in other
>> >>> browsers on other platforms. One thing I did play with is increasing
>> >>> the font size, becuase 10pt looks very small on Safari on the Mac. But
>> >>> that made fonts look uglier in the other browsers, so I dropped that.
>> >>>
>> >>> I think these few changes to the template.css fie would go a long way
>> >>> to making Scaladoc more readable.
>> >>>
>> >>> Thanks.
>> >>>
>> >>> Bill
>> >>> ----
>> >>> Bill Venners
>> >>> Artima, Inc.
>> >>> http://www.artima.com
>> >>>
>> >>
>> >
>> >
>> >
>> > --
>> > Bill Venners
>> > Artima, Inc.
>> > http://www.artima.com
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

My concern is just for a visual indicator that something might be clickable. I'm not fond of the current convention either, but having nothing at all... I don't know.
On Sun, Mar 20, 2011 at 16:30, Ruediger Keller <ruediger.keller@rk42.de> wrote:

Well, I thought about that too. But frankly I'm not too concerned.

There are other clickable areas in the current scaladoc that aren't
highlighted at all. The text with white background below the gray
signatures, for example.

Also, since when is gray background an indication of "clickable"? For
me it's not. And for the current scaladoc it's also not. Because it's
not consistent about this. Some gray backgrounds are clickable, some
are not. Examples: the class signature at the top of the file,
instance constructors, type members.

But! If you have a good idea for a visual indication of
"clickability", I'm more than willing to try to implement it.

Perhaps the white backgrounds need some getting used to, but I'm sure
the gray ones also did. So please give them a try.

Also, if everyone insists that signatures must have gray backgrounds,
I will create a version with it, but in my opinion it's just visual
noise that impedes scanning of the page.

Regards,
Rüdiger


2011/3/20 Daniel Sobral <dcsobral@gmail.com>:
> Well, one thing to be concerned about is that the grayed areas are clickable
> areas. With your suggestions, there's no indication at all of what is a
> clickable area. Something must be done about this.
>
> On Sun, Mar 20, 2011 at 06:23, Ruediger Keller <ruediger.keller@rk42.de>
> wrote:
>>
>> Hi Bill,
>>
>> I'm answering your question from the other thread here.
>>
>> > Can you elaborate on which section you are concerned about? Is it when
>> > you click on a method name, and it pops out the long description
>> > (which works really nicely now, by the way), the name of the param is
>> > a bit higher than the description?
>>
>> Yes, that's exactly what I am referring to. The parameter descriptions
>> at the bottom of the expanded method descriptions. I think it would
>> look better if the parameter names were aligned with the first line of
>> description.
>>
>> I will try to improve the layout a bit more and that is one of the
>> points on the list. If you don't mind I will use your suggestion as
>> the basis for my work.
>>
>>
>> @everyone: If someone has ideas for improvement, please speak up. I'm
>> no user interface designer, I just happen to know a little bit of CSS.
>> Also, I would like to hear how you like my initial proposal, where I
>> changed the style for the value members list. Bill was so kind to put
>> up a version of his ScalaTest Scaladocs with it:
>>
>> Original:
>> http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html
>>
>> My suggestions:
>> http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html
>>
>>
>> I think my suggestion can be improved further, but first I want to
>> know it it's worth the time. If everyone is in favor of the old style
>> with alternating grey and white, I will not pursue this approach.
>>
>> Hmm, I just noticed it looks much better if the separating lines
>> aren't black but light gray. Perhaps I will first put up a further
>> improved version and then everyone can comment.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/19 Bill Venners <bill@artima.com>:
>> > Hi Rüdiger,
>> >
>> > Can you elaborate on which section you are concerned about? Is it when
>> > you click on a method name, and it pops out the long description
>> > (which works really nicely now, by the way), the name of the param is
>> > a bit higher than the description?
>> >
>> > Bill
>> >
>> > On Sat, Mar 19, 2011 at 3:10 PM, Ruediger Keller
>> > <ruediger.keller@rk42.de> wrote:
>> >> I like the suggested changes. Although for methods, in the section for
>> >> the method parameters at the bottom, the parameter names are now even
>> >> less properly aligned with the parameter description to the right.
>> >> Nonetheless the changes are a net gain.
>> >>
>> >> Regards,
>> >> Rüdiger
>> >>
>> >>
>> >> 2011/3/19 Bill Venners <bill@artima.com>:
>> >>> Hi All,
>> >>>
>> >>> I've came up with some suggested changes to the template.css file.
>> >>> Here's the before:
>> >>>
>> >>> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>> >>>
>> >>> And here's the after:
>> >>>
>> >>> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>> >>>
>> >>> The differences are:
>> >>>
>> >>> I changed the line height from 1 to 1.1. This little tweak makes the
>> >>> paragraphs easier to read in my opinion. The lines are currently
>> >>> sitting  too much right on top of each other.
>> >>>
>> >>> I increases the margin around paragraphs in comments by quite a bit,
>> >>> from 0.4em to 0.9em. The paragraphs were also very close together,
>> >>> which made it hard to visually separate them.
>> >>>
>> >>> I increased the padding for short comments from 0 to 2px to add just a
>> >>> tad of space there. (As Ruediger Keller pointed out in his earlier,
>> >>> they were also squished together.)
>> >>>
>> >>> And what's a bit wierd is I decreased the padding for signatures from
>> >>> 3px to 2px. This made it look more uniform to me once the short
>> >>> comment had a 2px padding.
>> >>>
>> >>> Diff is:
>> >>>
>> >>> [sites@artima01 sdp]$ diff original/lib/template.css
>> >>> suggestion/lib/template.css
>> >>> 20c20
>> >>> <   line-height: 1;
>> >>> ---
>> >>>>   line-height: 1.1;
>> >>> 172c172
>> >>> <   padding: 3px;
>> >>> ---
>> >>>>   padding: 2px;
>> >>> 234,235c234,235
>> >>> <       margin-bottom: 0.4em;
>> >>> <       margin-top: 0.4em;
>> >>> ---
>> >>>>       margin-bottom: 0.9em;
>> >>>>       margin-top: 0.9em;
>> >>> 362c362
>> >>> <   padding: 0;
>> >>> ---
>> >>>>   padding: 2px;
>> >>>
>> >>> This is a difference off of 2.9.0-SNAPSHOT of one day ago. Sorry I
>> >>> haven't checked out the trunk yet. I'll do that later today. Let me
>> >>> know if things have changed too much since I grabbed the template.css
>> >>> file that you'd prefer I give you a diff off of trunk.
>> >>>
>> >>> I tested this in Safari and Firefox on the Mac and Explorer and
>> >>> Firefox on Windows. Would be good to have others look at it in other
>> >>> browsers on other platforms. One thing I did play with is increasing
>> >>> the font size, becuase 10pt looks very small on Safari on the Mac. But
>> >>> that made fonts look uglier in the other browsers, so I dropped that.
>> >>>
>> >>> I think these few changes to the template.css fie would go a long way
>> >>> to making Scaladoc more readable.
>> >>>
>> >>> Thanks.
>> >>>
>> >>> Bill
>> >>> ----
>> >>> Bill Venners
>> >>> Artima, Inc.
>> >>> http://www.artima.com
>> >>>
>> >>
>> >
>> >
>> >
>> > --
>> > Bill Venners
>> > Artima, Inc.
>> > http://www.artima.com
>> >
>
>
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

--
Daniel C. Sobral

I travel to the future all the time.

Hi All,

I incorporated some feedback from Ruediger into my template.css
suggestion for 2.9.0. I tried to make the minimal, lowest risk changes
that would achieve the goal of improving Scaladoc readability for
2.9.0. The two changes I made from my previous suggestion in this
iteration was:

1) increase line-height from 1.1em to 1.2em
2) make some adjustments to the parameter, etc., lists at the end of
full comments so the padding wasn't so large and the parameter name
and its comment line up.

You can see the result here:

http://www.artima.com/sdp/suggestion2/

I made my changes off of the snapshot I grabbed two days ago, which is here:

http://www.artima.com/sdp/original/

The diff from the old template.css file from two-days-ago 2.9.0-SNAPSHOT is:

[sites@artima01 sdp]$ diff original/lib/template.css
suggestion2/lib/template.css
20c20
< line-height: 1;
---
> line-height: 1.2;
172c172
< padding: 3px;
---
> padding: 2px;
234,235c234,235
< margin-bottom: 0.4em;
< margin-top: 0.4em;
---
> margin-bottom: 0.9em;
> margin-top: 0.9em;
362c362
< padding: 0;
---
> padding: 2px;
368a369,370
> margin-top: 2px;
> margin-bottom: 2px;
415a418,421
> div.fullcomment dl.paramcmts dd.cmt p {
> margin-top: 2px;
> margin-bottom: 2px;
> }

You can of course download the entire template.css file from:

http://www.artima.com/sdp/suggestion2/lib/template.css

Other than fixing issues 4358 and 4366, this is the only other
Scaladoc change I think needs to be put into 2.9.0. Everything else
could wait until a later release.

Should I make a ticket for this? This is more like an enhancement request.

Thanks.

Bill

On Sat, Mar 19, 2011 at 3:19 PM, Donna Malayeri wrote:
> Rüdiger,
>
> I'll be in charge of some of the Scaladoc tasks for the next few months, and I quite appreciate your suggestions and your new CSS layout (particularly as I'm still learning the intricacies of CSS). So, to answer your question--yes!  We would love more suggestions, and refined a CSS if you have time. I think the visual design of Scaladoc is quite important, and I am quite happy to see so many contributions and comments from the community.
>
> thanks,
> Donna
>
> On Mar 19, 2011, at 9:23 PM, Rüdiger Keller wrote:
>
>> Nice to see that someone looked at my suggestions. I have to admit
>> they aren't very refined, but I could create a more refined version if
>> there is demand for it.
>>
>> Also, in my opinion the method parameters and attributes at the bottom
>> of method docs need some love. The spacings are irregular and the
>> parameter names aren't aligned with the parameter descriptions.
>>
>> Should I post some more suggestions?
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/19 Bill Venners :
>>> Hi All,
>>>
>>> I put up a version of ScalaTest's Scaladoc with Rüdiger's suggested
>>> changes to the CSS file. You can compare the output of the original:
>>>
>>> http://www.artima.com/sdp/original/org/scalatest/GivenWhenThen.html
>>>
>>> With what it looks like with your suggested changes:
>>>
>>> http://www.artima.com/sdp/ruediger/org/scalatest/GivenWhenThen.html
>>>
>>> If you click on Any and AnyRef you'll get more methods to see how it
>>> looks. I think I like the alternating gray and white better than the
>>> lines, but agree that adding a bit more margin above and below each
>>> entry in the list is an improvement. I'll work on a suggested set of
>>> changes to the css file right now and point you to it once I'm done.
>>>
>>> Thanks.
>>>
>>> Bill
>>>
>>> On Sat, Mar 19, 2011 at 2:48 AM, Rüdiger Keller
>>> wrote:
>>>> Hello,
>>>>
>>>> I'm no Scala committer, so I don't know if it is really ok for me to
>>>> post on this list, but I read the conversation and was reminded of the
>>>> shortcomings of the current Scaladoc layout.
>>>>
>>>> Perhaps it's just me, but I find the current layout very hard to parse
>>>> visually, especially the lists of members. All the grey and white
>>>> alternating is more distracting that helping to bring structure to the
>>>> layout, IMHO. Also, there is generally a lack of padding, making
>>>> everything look very cramped and tangled up.
>>>>
>>>> I would like to suggest the following changes to the CSS, which I
>>>> threw together in a quick Firebug session. It's just two added lines
>>>> and one removed line:
>>>>
>>>> div.members > ol > li {
>>>>  display: block; /* unchanged */
>>>>  border-bottom: 1px solid black; /* new */
>>>>  padding: 5px 0; /* new */
>>>> }
>>>>
>>>> .signature {
>>>>  /* removed background-color, everything else is unchanged */
>>>>  clear: both;
>>>>  display: block;
>>>>  font-family: monospace;
>>>>  font-size: 10pt;
>>>>  padding: 3px;
>>>> }
>>>>
>>>> If you use something like Firebug it takes only a minute to try it. I
>>>> would be happy to see changes like this make its way into the official
>>>> Scaladoc. Also, I would like add additional padding to various places,
>>>> to make the layout less cramped. But that is less of an issue compared
>>>> to the member lists.
>>>>
>>>> Regards,
>>>> Ruediger Keller
>>>>
>>>>
>>>>
>>>> 2011/3/19 Bill Venners :
>>>>> Hi Kato,
>>>>>
>>>>> I was able to build the docs with the latest 2.9.0-SNAPSHOT, by not
>>>>> attempting to compile the tests. (Even with Paul's patch I still got
>>>>> the same stack trace. I'm probably doing the same thing elsewhere in
>>>>> the tests.) I put up what it looks like with the normal css file here:
>>>>>
>>>>> http://www.artima.com/scaladocprobs2/
>>>>>
>>>>> I went through and verified that all the bugs we submitted to trak
>>>>> today exist when using the normal css file.
>>>>>
>>>>> To get a feel for the kind of changes I would suggest we do to the css
>>>>> file, compare:
>>>>>
>>>>> http://www.artima.com/scaladocprobs2/org/scalatest/Suite.html
>>>>>
>>>>> with:
>>>>>
>>>>> http://www.artima.com/xxx/scaladocprobs/org/scalatest/Suite.html
>>>>>
>>>>> I tried and it does seem to work now. That bug report was
>>>>> closed already, but I wanted to check it. So at this point the main
>>>>> thing I'd suggest is we put a bit more space between paragraphs, and
>>>>> likely a bit more space between the lines. You could also consider
>>>>> using a serif font. Tomorrow I'll try and figure out what amounts I
>>>>> used in my css file. It isn't a simple diff anymore because your file
>>>>> has changed so much since I forked it, and I don't have the one I
>>>>> forked it from. Anyway, I should be able to make some concrete
>>>>> suggestions for that tomorrow.
>>>>>
>>>>> Thanks.
>>>>>
>>>>> Bill
>>>>>
>>>>> On Fri, Mar 18, 2011 at 4:05 PM, Kato Kazuyoshi
>>>>> wrote:
>>>>>> Hi Bill,
>>>>>>
>>>>>> I've checked the issue but I can't reproduce on my environment.
>>>>>>
>>>>>> On Fri, Mar 18, 2011 at 8:42 PM, Bill Venners wrote:
>>>>>>>
>>>>>>> Another thing I did in ScalaTest 1.3 was replace a few parts of the
>>>>>>> CSS file generated by ScalaDoc to try and improve the readability and
>>>>>>> fix issues I could fix. I increased the distance between paragraphs
>>>>>>> for example. I think I had to make a change to make strong actually
>>>>>>> show up as bold, and to turn off an underline on things.
>>>>>>> I also changed to a serif font to better distinguish the difference
>>>>>>> between text and code font, but that kind of thing I don't mind doing
>>>>>>> myself. I'll try and dig up what changes I made and submit that as a
>>>>>>> suggestion as well. If I had more time I'd pitch in to help with
>>>>>>> ScalaDoc, but unfortunately I just haven't been able to find the time
>>>>>>> to do that this year.
>>>>>>>
>>>>>>
>>>>>> Hmm, I've noticed that http://www.artima.com/scaladocprobs/lib/template.css
>>>>>> don't have "display: none" on #comment.
>>>>>>
>>>>>> #comment {
>>>>>>  display:none;
>>>>>>  padding-right: 8px;
>>>>>>  padding-left: 8px;
>>>>>> }
>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> --
>>>>>> Kato Kazuyoshi
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Bill Venners
>>>>> Artima, Inc.
>>>>> http://www.artima.com
>>>>>
>>>>
>>>
>>>
>>>
>>> --
>>> Bill Venners
>>> Artima, Inc.
>>> http://www.artima.com
>>>
>
>

On Thursday March 17 2011, Bill Venners wrote:
> Hi,
>
> ...
>
> Bill

Might I suggest that someone with graphic arts training and experience
be consulted about improving the formatting and other presentation
characteristics of the Scaladoc HTML?

Randall Schulz

Hi Randall,

On Sun, Mar 20, 2011 at 7:59 PM, Randall R Schulz wrote:
> On Thursday March 17 2011, Bill Venners wrote:
>> Hi,
>>
>> ...
>>
>> Bill
>
>
> Might I suggest that someone with graphic arts training and experience
> be consulted about improving the formatting and other presentation
> characteristics of the Scaladoc HTML?
>
I'm not sure which email you're replying to, but your suggestion is a
good one. Perhaps that is Donna Malayeri, who forked off a different
thread from this one. Today I submitted a set of minimal changes to
the template.css file I'd suggest for 2.9.0. I don't have time to do
anything more than that. If it gets in, I think it will make Scaladoc
in general more readable for 2.9.0 and more can be done later. If it
doesn't get in, I'll use it in ScalaTest so that at least ScalaTest
users will get more readable docs.

Thanks.

Bill

I'm looking at both outputs. I find the 'after' version much easier on the eye.
In chrome on ubuntu, the content starts to go wrong at the deprecated groups() method. From that point on, text is bold. Also, I clicked on the groups text and instead of expanding it disappeared, and now it won't appear again. I think the reason is that there's an unclosed <strong> tag at line 2103, in the <p class="shortcomment cmt"> div of the group method. Perhaps the template for generating the short comment for deprecated methods is borked? I don't know.
Matthew

On 19 March 2011 21:34, Bill Venners <bill@artima.com> wrote:

Hi All,

I've came up with some suggested changes to the template.css file.
Here's the before:

http://www.artima.com/sdp/original/org/scalatest/Suite.html

And here's the after:

http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html

Hi Matthew,

The bold and open/close problem is caused by this Scaladoc bug:

https://lampsvn.epfl.ch/trac/scala/ticket/4366

You can ignore it when looking at style sheet spacing. The latest
iteration people are considering is this one:

http://www.artima.com/sdp/suggestion3/

Thanks.

Bill

On Mon, Mar 21, 2011 at 4:11 PM, Matthew Pocock
wrote:
> I'm looking at both outputs. I find the 'after' version much easier on the
> eye.
> In chrome on ubuntu, the content starts to go wrong at the deprecated
> groups() method. From that point on, text is bold. Also, I clicked on the
> groups text and instead of expanding it disappeared, and now it won't appear
> again. I think the reason is that there's an unclosed tag at line
> 2103, in the 

div of the group method. Perhaps
> the template for generating the short comment for deprecated methods is
> borked? I don't know.
> Matthew
>
> On 19 March 2011 21:34, Bill Venners wrote:
>>
>> Hi All,
>>
>> I've came up with some suggested changes to the template.css file.
>> Here's the before:
>>
>> http://www.artima.com/sdp/original/org/scalatest/Suite.html
>>
>> And here's the after:
>>
>> http://www.artima.com/sdp/suggestion/org/scalatest/Suite.html
>>
>

HI,

On 21 March 2011 23:17, Bill Venners <bill@artima.com> wrote:

Hi Matthew,

The bold and open/close problem is caused by this Scaladoc bug:

https://lampsvn.epfl.ch/trac/scala/ticket/4366

Ah, thanks for showing me that. 

You can ignore it when looking at style sheet spacing. The latest
iteration people are considering is this one:

http://www.artima.com/sdp/suggestion3/

My only other contribution, then, is to say that I find the behaviour when a parameter list wraps over multiple lines to be visually confusing. The 'def' keyword is indented by a lot, and when the parameter list wraps, it abuts the left margin of the cell. It would look better to my eye if the parameters wrapped to a margin level with the function name, or some fixed distance to the right of it.
Matthew 

Thanks.

Bill

Hi Matthew,

On Mon, Mar 21, 2011 at 4:34 PM, Matthew Pocock
wrote:
>> http://www.artima.com/sdp/suggestion3/
>>
>
> My only other contribution, then, is to say that I find the behaviour when a
> parameter list wraps over multiple lines to be visually confusing. The 'def'
> keyword is indented by a lot, and when the parameter list wraps, it abuts
> the left margin of the cell. It would look better to my eye if the
> parameters wrapped to a margin level with the function name, or some fixed
> distance to the right of it.
> Matthew
>
That's a good suggestion. That's more like we would write it in code.

Bill

>>
>> Thanks.
>>
>> Bill

Antonio, I just opened http://lampsvn.epfl.ch/trac/scala/ticket/4375, which might well be a duplicate, though the related tickets seemed to all relate to generics, which is not the case here (as far as I can see).

I bring this up because it is a regression (it works on 2.8.1 as expected), and it seriously hamper interoperability with Java. I discovered it while trying to call a method expected a Seq[Int] from Java (and before you check the ticket out, it's not related to Seq itself, so that generic is not relevant).

On Wed, Mar 16, 2011 at 19:03, Antonio Cunei <antonio.cunei@epfl.ch> wrote:

All,

After a bit of additional time spent on fixing tickets and improving features, we are aiming to get an RC1 release next week.

According to the messages I have seen so far, and the present status of the code, I currently have this list of tickets that are still open, and that various people considered important to address before the release of RC1:

http://lampsvn.epfl.ch/trac/scala/ticket/4205 (assigned moors)
http://lampsvn.epfl.ch/trac/scala/ticket/4202 (assigned plocinic)
http://lampsvn.epfl.ch/trac/scala/ticket/4012 (assigned dragos)
http://lampsvn.epfl.ch/trac/scala/ticket/4248 (assigned cunei)
http://lampsvn.epfl.ch/trac/scala/ticket/3623 (assigned extempore)
http://lampsvn.epfl.ch/trac/scala/ticket/4214 (assigned extempore)
http://lampsvn.epfl.ch/trac/scala/ticket/4305 (assigned moors)
http://lampsvn.epfl.ch/trac/scala/ticket/4337 (pending)

Anything else? Please let me know if you have additional issues that should definitely be addressed before 2.9.0, or if there is any further code that you think should go in and that is currently still pending.

Thanks!
Toni

--
Daniel C. Sobral

I travel to the future all the time.

Bill,

On Sunday March 20 2011, Bill Venners wrote:
> Hi Randall,
>
> On Sun, Mar 20, 2011 at 7:59 PM, Randall R Schulz wrote:
> > On Thursday March 17 2011, Bill Venners wrote:
> >> Hi,
> >>
> >> ...
> >>
> >> Bill
> >
> > Might I suggest that someone with graphic arts training and
> > experience be consulted about improving the formatting and other
> > presentation characteristics of the Scaladoc HTML?
>
> I'm not sure which email you're replying to, but your suggestion is a
> good one. ...

I deliberately replied to the first message that referred to the
Scaladoc output 'cause I wasn't responding to any specific aspect of
Scaladoc output.

Except white-space to the left of colons. I hate that. ... Except for
context bounds; it's good there.

> Bill

Randall Schulz

Hi Matthew,

regarding the wrapping of signatures, that is fixed in my proposed CSS
changes. Bill put up a site using it here:

http://www.artima.com/sdp/ruediger2/

Perhaps we should continue this discussion in the thread titled
"Scaladoc layout (was: Upcoming 2.9.0.RC1 (take 2))".

Regards,
Rüdiger

2011/3/22 Matthew Pocock :
> HI,
>
> On 21 March 2011 23:17, Bill Venners wrote:
>>
>> Hi Matthew,
>>
>> The bold and open/close problem is caused by this Scaladoc bug:
>>
>> https://lampsvn.epfl.ch/trac/scala/ticket/4366
>>
>
> Ah, thanks for showing me that.
>
>>
>> You can ignore it when looking at style sheet spacing. The latest
>> iteration people are considering is this one:
>>
>> http://www.artima.com/sdp/suggestion3/
>>
>
> My only other contribution, then, is to say that I find the behaviour when a
> parameter list wraps over multiple lines to be visually confusing. The 'def'
> keyword is indented by a lot, and when the parameter list wraps, it abuts
> the left margin of the cell. It would look better to my eye if the
> parameters wrapped to a margin level with the function name, or some fixed
> distance to the right of it.
> Matthew
>
>>
>> Thanks.
>>
>> Bill