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!

[mxub]

I don't know if it belongs here but another enhancement for the ```@doc """`-String would be to fold in the whole doc-string (or maybe any """-pair)

As seen in https://github.com/wojtekmach/req/blob/main/lib/req/steps.ex sometimes the doc-string gets very long and an easy way to hide it would be beneficial.

@doc """
  Adds default steps.

  ## Request steps

    * `encode_headers/1`

    * `put_default_headers/1`

    * `encode_body/1`

    * [`&put_base_url(&1, options[:base_url])`](`base_url/2`) (if `options[:base_url]` is set)

    * [`&load_netrc(&1, options[:netrc])`](`load_netrc/2`) (if `options[:netrc]` is set
      to an atom true for default path or a string for custom path)

    * [`&auth(&1, options[:auth])`](`auth/2`) (if `options[:auth]` is set)

    * [`&put_params(&1, options[:params])`](`put_params/2`) (if `options[:params]` is set)

    * [`&put_range(&1, options[:range])`](`put_range/2`) (if `options[:range]` is set)

    * [`&run_steps(&1, options[:steps])`](`run_steps/2`) (if `options[:steps]` is set)

  ## Response steps

    * [`&retry(&1, options[:retry])`](`retry/2`) (if `options[:retry]` is set to
      an atom true or a options keywords list)

    * [`&follow_redirects(&1, options[:follow_redirects])`](`follow_redirects/2`)

    * `decompress/1`

    * `decode_body/1`

  ## Error steps

    * [`&retry(&1, options[:retry])`](`retry/2`) (if `options[:retry]` is set and is a
      keywords list or an atom `true`)

  ## Options

    * `:base_url` - if set, adds the `put_base_url/2` step

    * `:netrc` - if set, adds the `load_netrc/2` step

    * `:auth` - if set, adds the `auth/2` step

    * `:params` - if set, adds the `put_params/2` step

    * `:range` - if set, adds the `put_range/2` step

    * `:cache` - if set to `true`, adds `put_if_modified_since/2` step

    * `:raw` if set to `true`, skips `decompress/1` and `decode_body/1` steps

    * `:retry` - if set, adds the `retry/2` step to response and error steps

    * `:steps` - if set, runs the `run_steps/2` step with the given steps

    * `:follow_redirects` - if set, runs the `follow_redirect/2` step with the given list
       of options

  """
  @doc step: :request
  def put_default_steps(request, options \\ []) do
    request_steps =
      [
        {Req.Steps, :encode_headers, []},
        {Req.Steps, :put_default_headers, []},
        {Req.Steps, :encode_body, []}
      ] ++
        maybe_steps(options[:base_url], [{Req.Steps, :put_base_url, [options[:base_url]]}]) ++
        maybe_steps(options[:netrc], [{Req.Steps, :load_netrc, [options[:netrc]]}]) ++
        maybe_steps(options[:auth], [{Req.Steps, :auth, [options[:auth]]}]) ++
        maybe_steps(options[:params], [{Req.Steps, :put_params, [options[:params]]}]) ++
        maybe_steps(options[:range], [{Req.Steps, :put_range, [options[:range]]}]) ++
        maybe_steps(options[:cache], [{Req.Steps, :put_if_modified_since, []}]) ++
        maybe_steps(options[:steps], [{Req.Steps, :run_steps, [options[:steps]]}])

    retry = options[:retry]
    retry = if retry == true, do: [], else: retry

    raw? = options[:raw] == true

    response_steps =
      maybe_steps(retry, [{Req.Steps, :retry, [retry]}]) ++
        [{Req.Steps, :follow_redirects, [options[:follow_redirects]]}] ++
        maybe_steps(not raw?, [
          {Req.Steps, :decompress, []},
          {Req.Steps, :decode_body, []}
        ])

    error_steps = maybe_steps(retry, [{Req.Steps, :retry, [retry]}])

    request
    |> Req.Request.append_request_steps(request_steps)
    |> Req.Request.append_response_steps(response_steps)
    |> Req.Request.append_error_steps(error_steps)
  end

[sergchernata]

@danilokleber can you share all of your modifications?

[danilokleber]

@sergchernata sorry for the delay. I'm actually moving away from Sublime Text. Anyway I tried to find the patched syntax file, but could not find it. I guess the package got updated with the changes mentioned in this issue? I can't remember. Sorry I can't help.

[danilokleber]

It's been a while 😄 I got back to Sublime Text and was happy to see that this project had made to the official Elixir editors repo. That is much deserved. Congrats and thank you!

As this is still open I guess we still don't have a way to customize the look of @spec sections, right? I just want to make sure.

[azizk]

Hi, welcome back and thanks! 😄

I haven't looked further into this and tbh forgot about it with time. Just gave it another go and it seems possible to add a meta.spec.elixir scope with this syntax definition:

  spec_definition_pop:
    - meta_scope: meta.spec.elixir
    - match: (?=\()
      set: [spec_metascope_pop, type_definition_next_pop, type_arguments_or_pop]
    - include: type_definition_next_pop

  spec_metascope_pop:
    - meta_scope: meta.spec.elixir
    - include: if_empty_pop

The trouble is then to style all possible tokens under this meta scope. I tried the following:

    {
      "name": "Specs",
      // "scope": "meta.spec.elixir & (storage.type.custom.elixir | constant.other.keyword.elixir)",
      "scope": "meta.spec.elixir storage.type.custom.elixir",
      "foreground": "color(var(doc))"
    }

The first commented out scope selector should work, but in this instance it doesn't. Don't understand why because it works in other style rules. Go figure...