Ayu: Please don't make comment italic. Instead mark it with different color than doc comment.

[tesuji]

This is just my personal taste.
I'm never a fan of making comments italic. It is hard to read for me.

Rather, I really enjoy what Dark and Light theme is doing: Mark doc comments with different color than normal comments.

cc @Cldfire @jyn514 @GuillaumeGomez

[jyn514]

Can you add a screenshot of what this looks like in both Ayu and Dark themes?

[tesuji]

Here in Ayu and Dark theme respectively:

[tesuji]

I was searching about the italic comment topic and found that people prefer both.
But I think the good choice is to default to non-italic and add a rustdoc config to change to italic.

[GuillaumeGomez]

But I think the good choice is to default to non-italic and add a rustdoc config to change to italic.

We will definitely not add a rustdoc config for that (way too specific). :)

[Cldfire]

Thanks for your critique of the theme, it's been very helpful :)

I would like to keep the comment style italic because:

• It provides a rustdoc theme with italic comments for those who like it (if one dislikes this there are two other themes that don't make this choice)
• The Ayu theme everywhere else has italic comments, example:

I don't want to break with the standard Ayu look in this regard unless a significant number of people find the italics to be a problem.

As far as the color being different between doc comments and normal comments, I am personally against this. I've never seen an editor highlight doc comments differently from normal comments, nor do I see a reason to do so. The only thing that sets doc comments apart from normal comments is that they are present in the generated rustdoc HTML, and to me this is not a reason to introduce an entirely new color into the mix just for the sake of styling them differently (why would you care about this when reading the comment? What benefit does the color being different from a normal comment provide, and does that benefit outweigh the visual clutter introduced by using another color? I'm interested to hear your thoughts about this).

Here I would say similar to the above: the Ayu theme provides a choice to view comments with a unified color. If one dislikes this, there are two other themes available with that feature 🙂.

[GuillaumeGomez]

@Cldfire I'd like to comment in favour of removing the italic. In here it's important to remember that themes are only supposed to change colors, not presentation. Adding italic on comments is breaking the coherency with the other themes and I think it should be removed, even though the original theme has it (are you sure it's the theme and not the IDE btw?).

[Cldfire]

@Cldfire I'd like to comment in favour of removing the italic. In here it's important to remember that themes are only supposed to change colors, not presentation. Adding italic on comments is breaking the coherency with the other themes and I think it should be removed

That's a fair point, I can agree with that.

even though the original theme has it (are you sure it's the theme and not the IDE btw?).

Yes it is the theme 😉

[Mark-Simulacrum]

As far as the color being different between doc comments and normal comments, I am personally against this. I've never seen an editor highlight doc comments differently from normal comments, nor do I see a reason to do so.

I will note that my vim configuration at least does this and I personally quite like it -- I differentiate between regular comments and doc comments when reading. Regular comments are intended for the programmer and doc comments for the end-user of the API; those are at least for me two different mindsets.

[tesuji]

I don't want to break with the standard Ayu look in this regard unless a significant number of people find the italics to be a problem.

Thanks for letting me know about its origins. I've never used Ayu theme in editor other than in mdbook and rustdoc. It is great.
This issue (microsoft/vscode#32579) is not related to rustdoc
but it points out a group of people finding a way to disable italic on comments and language keywords
on VS Code.

I've never seen an editor highlight doc comments differently from normal comments

I wish Rust-Enhancement package (Sublime Text) render they differently. rust.vim already did it.
Mark already posted a reason for the difference: #74770 (comment)

[Cldfire]

As far as the color being different between doc comments and normal comments, I am personally against this. I've never seen an editor highlight doc comments differently from normal comments, nor do I see a reason to do so.

I will note that my vim configuration at least does this and I personally quite like it -- I differentiate between regular comments and doc comments when reading. Regular comments are intended for the programmer and doc comments for the end-user of the API; those are at least for me two different mindsets.

Interesting! Thanks for chiming in.

Your point about who each type of comment is written for makes sense 👍 I'll look into a color that would make sense to use for doc comments in the theme here.

[Lokathor]

I'll throw another vote in favor of not using italics. They are, in general, a poor experience with monospaced fonts.

[GuillaumeGomez]

I will note that my vim configuration at least does this and I personally quite like it -- I differentiate between regular comments and doc comments when reading.

If people are interested, we could use a different color for the doc comments. It sounds like a good add.

[Cldfire]

I played around with some options and I believe #f9ca89 meshes reasonably well as a doc comment color.

Before:

After:

Another potential option that draws less attention away from the code itself is #a1ac88:

Thoughts on this?

[GuillaumeGomez]

I find the last proposal better, but maybe we should put it into another issue to not lose track of the original issue? ;)

[Cldfire]

Opened a new issue :)