Change highlighting of documentation snippets

[danilokleber]

Hey there! Firstly thanks a lot for this syntax. I am so glad I can rely on "Go to symbol/definition" after installing it!

The issue is not actually an issue. I just want to tweak my color scheme so that documentation snippets (@doc for example) do not highlight as Markdown or Elixir code itself. I like when they show as regular comments. Do you know which scope should I use to achieve that?

[azizk]

Hey! Glad you like it! Just look at the lines where markdown_comment is included in Elixir.sublime-syntax. You can simply remove those. 👍

[danilokleber]

Thank you for the quick response! It worked but now it highlights """snippet""" like a string, which makes total sense but do you know how can I make it all look like a comment? Sorry if that is an irrelevant question.

[danilokleber]

Nevermind, I managed to do it. Sorry for the buzz and thanks again!

[azizk]

No worries! So the solution seems to be a bit more involved then. In the Elixir syntax file add a meta scope like so:

    # Special attributes:
    - match: (?>(?>module|type|short)?doc){{no_suffix_then_arguments}}
      scope: support.attr.doc.elixir
      set:
        - match: \(
          scope: punctuation.section.arguments.begin.elixir
          set:
            - meta_scope: meta.doc.elixir
            - include: arguments_closing_pop
            - match: ''
              push:
                - include: if_closing_token_pop
                - include: arg_comma_and_skip_ws
                # - include: markdown_comment
                - include: core_syntax
        - match: \s?
          scope: punctuation.section.arguments.begin.elixir
          set:
            - meta_scope: meta.doc.elixir
            - include: arguments_ws_closing_pop
            - include: arg_comma_and_skip_ws
            # - include: markdown_comment
            - include: core_syntax

And then in your themes file, like Monokai.sublime-color-scheme, change the doc string scope to "meta.doc.elixir string".

    {
      "name": "Doc string",
      "scope": "meta.doc.elixir string",
      "foreground": "var(yellow5)"
    }

I'm going to leave this open because we should add the meta.doc.elixir meta scope and also document some customization solutions somewhere. I'll push these changes with some other things I have in line soon.

[danilokleber]

Hi! Sorry for reaching out again but how could I also customize spec and other special attributes? I tried to play around with the file you gave instructions but couldn't get much far. If that is already on the plans you mentioned, thanks in advance!

[azizk]

Hey, happy to help! How would you like to customize the spec attribute specifically? Didn't have a plan for that yet but I could add it as a use case.

[danilokleber]

You're awesome! So with your suggestions I ended up with this highlighting:

I'd like to have everything defined by @doc (and variations) and @spec (are there variations?) to be highlighted as a comment. That means even the """ in the @doc example.

Thanks a lot for the individualized help.

[azizk]

Okay, so to make the string delimiters of the doc strings grey is the easiest part. You probably only need to set a style for meta.doc.elixir punctuation.definition.string.begin (and end). To make all the specs grey is much more tricky. Because you need to override the style for each syntax element that can appear in it (ids, punctuation, operators...) The color scheme rules aren't as flexible as CSS. There are variants of spec but I guess you don't want to grey all of them. The problem is that a lot of the regex rules are shared among spec/type attribute rules. There isn't a quick solution afaics, but I'll give it some further thought. Maybe there's something I didn't consider. Perhaps a Python script that finds and styles specs specially? But I'm afraid I can't help you much with scripting atm.

In any case, it's interesting because I think I wanted to do something similar. I also wanted specs to not stick out as much. The best I could do is desaturate the color of the spec name and the type identifiers. Even ST4 doesn't give you a lot of possibilities to solve something like this I think. Anyway, hope you'll make do somehow. :)

[princemaple]

Maybe spec should have a meta scope, will it allow better customization? I'm not very familiar with color scheme customization, just throwing ideas around.

[azizk]

Yep, I was gonna add such a scope. It will be there in the next release. But it turns out that even adding a meta scope like that isn't simple because it unfortunately doesn't cover everything and you have to add it in several more context rules. :/

Still, even with the meta scope you'll have to target every token in order to style it as a comment.

[danilokleber]

I'm satisfied with the way @doc looks now and understand that @spec is a lot trickier. Unfortunately I can't help with a solution but I thank you guys very much for the patience and this project. Keep it up!