void/given/satisfies appear in grey color in ceylon doc

[gavinking]

The keywords void, given, and satisfies are highlighted in a grey color, instead of the magenta we use everywhere else. Is this intentional?

[thradec]

Only reason is, not call too much attention on itself.

[thradec]

Does it look better? ... no for me

[FroMage]

They're shy keywords ;)

[gavinking]

To my eyes it looks better, yes, mainly because it's the same color scheme we use everywhere else. But ... are they in bold? We can at least unbold them, I guess.

[loicrouchon]

On the mailing list (https://groups.google.com/forum/#!topic/ceylon-dev/Q3f3zyd_8bI) Luke referenced this article http://zeroturnaround.com/rebellabs/rebelrant-syntax-highlighters-should-emphasize-definitions-not-keywords-and-boilerplate/

I'm just saying this because this issue arises because keywords are emphasize. Maybe doing it for definitions / declaration instead of keywords would help

[gavinking]

I read that article but I don't necessarily agree with it. The assumption is that when I see a declaration the thing I'm looking for first is its name. I'm not sure that's true. The first thing I want to know, IMO, is what kind of construct am I looking at. Emphasizing class, interface, satisfies, etc, helps me parse the structure of the thing and then quickly guides my eyes to the bit of the declaration i'm interested in.

OTOH, perhaps I'm just that I'm so used to having the emphasis on the keywords.

[loicrouchon]

I'm not saying we should. On my side too I "prefer" with emphasized keywords, most probably because I'm used to.

An example of alternative highlighting the html snippet we have on http://ceylon-lang.org/ (purple types / constructor calls) I quite like this example, but would need to see more of it (with keywords, class definition, ...) Again, this is just an idea. If you find it interesting, we could open a dedicated issue for it and close this one by fixing given highlighting.

[gavinking]

An example of alternative highlighting the html snippet we have on http://ceylon-lang.org/ (purple types / constructor calls)

Well that sorta works with white-on-black text, but I'm skeptical it would work as nicely with black-on-white.

[FroMage]

Well, I would argue that indeed it's better that they stay gray, except the leading interface which seems like important information.

[FroMage]

@gavinking @tombentley @quintesse opinions?

[gavinking]

I think we should be consistent across the whole website and the ide. They should be magenta, as they are in other places.

[FroMage]

I don't think documentation must be consistent with syntax highlighting. Documentation is about what's important on a given page, not about code. Now, perhaps we need to make the list of type parameters displayed less as code and more as something else.

[gavinking]

Whether you like it or not, that is code written in the language syntax, not documentation. And our eyes are trained to respond to the syntax highlighting we're used to staring at all day. By displaying it in a different color to what we're used to seeing on the rest of the website and in the IDE, you're just confusing my brain and making it harder to read.

[quintesse]

I think I agree somewhat with @gavinking . I also notice that the difference between light gray for keywords and dark gray for names is not enough and I keep re-reading to figure out which is which.

Also, in the example above, why does Annotated as a default type argument have a different color than Annotated used as a satisfies clause? To my mind different colors mean they're not related.

[thradec]

So what about this? (I used less shiny shade of magenta)

[FroMage]

Would it look better or worse if we removed the whole signature-like thing and kept only interface ConstrainedAnnotation and listed the type parameters under a Type Parameters section similar to the Attributes/Methods ones?

[FroMage]

I think it would look better since we could then tie the given clauses back next to the type parameter they belong to.

[tombentley]

FTR I agree with @gavinking that consistency is important here. However @thradec that less magenta colour is preferable.

@FroMage imo it would be worse because then it wouldn't read like a ceylon declaration.

[FroMage]

It already doesn't read like a Ceylon declaration, it doesn't have to, it's documentation. The type hierarchy part is somewhere else, along with attributes/methods. I don't think that's a valid argument.

[gavinking]

Seriously Stef, there is a huge amount of value in having a conventional way of presenting these things. It doesn't necessarily have to be the best way, it's just the same way as everywhere else. Once you start doing things different, you make people have to adjust.

[tombentley]

The type hierarchy part is somewhere else

And you know what? That's terrible! I have all this information about type parameters in a HUGE typeface and the often far more important information about supertypes is much less obvious.

[gavinking]

And you know what? That's terrible!

I agree. It's actually pretty annoying that the direct supertypes aren't there in the header.

[FroMage]

Well, we can't put everything in huge typeface, and not everything looks better declaration-style, otherwise we'd just put everything out of sections and as code. We already have another issue open about the type hierarchy and I agree the current presentation is not ideal, and we should have something with tabs further down with attributes/methods. I think the most important thing is the name and the type of object we're dealing with (interface/class/etc), then the documentation, then the type params, supertypes, attributes, methods.

In fact, I find this presentation far more readable than the current half-signature:

Name	Bound	Default
Value	satisfies Annotation	= Annotation
Values
ProgramElement	satisfies Annotated	= Nothing

And perhaps that allows us to add documentation to type parameters themselves.

[FroMage]

I mean, you can't claim that seeing supertypes is more important than seeing members. That'd be totally arbitrary and wrong for lots of use cases. Most times I look at documentation I only care about members, but that doesn't mean I want to see members better than supertypes. I agree supertypes should be displayed better, using tabs to select how to show supertypes, subtypes, whatever, but they should move down below the documentation itself, which is more important, and types should not look prominent than members, though I don't care if it's listed before them.

[quintesse]

In fact, I find this presentation far more readable

I don't honestly. The more it looks like the "real thing" the less I have to interpret what I'm looking at.

[FroMage]

Look, if you all think it looks better when it requires multiple scans to put back the type parameter bounds with the type parameters, and that type parameters matter as much as the name of the object, and that for some reason type parameters must be listed in a way that is irregular with the other categories documented in a type, then what can I say? Keep it up there where it clutters, and by all means add more clutter like types up there. I strongly believe you're all nuts, but I won't stop you ;)

[quintesse]

I understand why you say that, but it does seem consistent with what we do for members and such, we show the entire definition (names, types, arguments, defaults, etc) without putting them in tables or otherwise formatting them different from how they look in code.

Now, for members we do have a first column that only contains the name, so we could indeed just have a topmost name without anything else and directly below it what we have now. It would be more like the JavaDoc does it.

I have always liked btw how the first thing in JavaDoc is the hierarchy if supertypes and after that a list of subclasses. I use that all the time. We have that of course, it's just a bit less visible.

[quintesse]

What I mean is that the info about types and the actual documentation are not very much separated visually.

[thradec]

Color changed (for other discussed proposals, please open separate issue)