Separate syntax highlight rules for structured documentation comments


#1

Recently, I tried to add some JSDoc style comments in a module I wrote in which structured tokens of the documentation are as bright and highlighted as the main body of the code. This makes it very difficult to follow the code due to this extra distraction. I tried various themes, but all behaved the same way, they did not seem to distinguish between the tokens of the main code and those in the comment. I would like this documentation to be grayed out and sit in the background to be only noticed when paid explicit attention. Even if it has some colored tokens, they should not be as bright as the main code.


#2

What language package do you have active? The complexity of the solution will depend on whether or not you want to keep some or all of the colors.


#3

The package language-javascript is active in this file. I think, rather than solving this problem on per-language basis, there should be an elegant way of applying some classes on the recognized commented lines generally. Then it will be possible to apply styles on tokens of documentation differently from the non-commented lines. For example, adding a different brightness to commented lines while still having tokens colored if necessary.


#4

You’re mistaken. It’s not a language problem and isn’t going to be solved on a per-language basis. It’s a “problem” with the theme because the theme creator didn’t put a rule in the theme saying, “If this colored text is within a comment, dim it”. That’s really easy to do from within a theme. It’s not much harder to do from the outside given how Atom is designed. What you want to do is take a look at the source for both the language grammar and the theme you’re using (I’ll use one-dark-syntax for examples; many themes are patterned off of the one-dark and one-light themes). You can also open the inspector (View -> Developer -> Toggle developer tools) and search for the elements representing your JSDoc text to identify the classes being applied.

Because Atom uses Less stylesheets and compiles them all together, you can use the variables designated by your theme. Therefore, if you’re using one-dark-syntax or one of the many themes based on it (like I am), you can make both parts of, for example, // @author Doomy McDoomerson darker using the following code in styles.less:

@import "syntax-variables.less";

.syntax--comment {
    .syntax--storage {
        color: darken(@hue-3, 20%);
    }

    .syntax--entity.syntax--name.syntax--type {
        color: darken(@hue-6-2, 20%);
    }
}

Rinse and repeat for all other unique class combinations in jsdoc.cson and you’re good to go.


#5

Thanks @DamnedScholar, you are awesome.

That said, I think this approach does not seem very generic. I wish there was a way to apply some styles by increasing the specificity of the .syntax--comment class (selectively), preferably by the theme itself, so that there is no need to identify all possible tokens in comments that might depend on specific documentation styles. I think I should open a ticket in the theme’s repo.


#6

Posted a reference to this thread in a somewhat relevant ticket at https://github.com/atom/one-dark-syntax/issues/99


#7

I don’t believe Less is capable of that level of computation. No, the answer for a theme creator would be to do the exact same thing I did for each JSDoc class combination.

Would you be satisfied with a solution that just doesn’t inject the JSDoc grammar? The language-javascript-jsx package doesn’t have any highlighting inside of comments.


#8

The problem with solving using this approach is the brittleness of the solution as it is heavily dependent on the grammar of one documentation system. While the code you suggested was a great fix for me for this particular project, I would much prefer a more generic approach which does not solve only my problem and only for this language+doc syntax. Since comments are a more abstract construct independent of the language, there should be a better way style that from the theme level, irrespective of additional structure they might have.

Just thinking out loud, there might be a way to overcome this by using repeated class chaining trick to increase the specificity such as .syntax--comment.syntax--comment.syntax--comment and by using wildcard child selector such as .syntax--comment *. I did not try either of these and I am not sure how much the theme authors would be willing to dictate style of those structures in the comment, but I really wish there was a way.


#9

This works just fine.

.syntax--comment * {
  color: cadetblue !important;
}