Highlight @doc as comment

[pdilyard]

Things look a lot cleaner if you highlight the following blocks as if they were comments:

@moduledoc """
Everything in here should be gray, including the @moduledoc and triple-quotes
"""

@doc """
Everything in here should be gray, including the @doc and triple-quotes
"""

Most other Elixir syntax highlighters handle things this way (including the Github one, as shown above). It tends to make things look a bit cleaner in larger modules.

If people agree, I could try to work on a PR for this.

[whatyouhide]

I would have to use this for a while to be able to tell for sure if I like it or not, but I think I like the idea. 👍

[tonini]

@pdilyard @whatyouhide I'll make a PR so you guys could work with this variate for a bit.

[pdilyard]

@tonini thanks, I'd appreciate that!

[andreas-roehler]

Hmm, at Python we have a docstring face for that. As comments and strings are syntactically different, should they get the same face?

[gausby]

We could use font-lock-doc-face for fontification of @doc- and @moduledoc strings. I think that would make sense.

font-lock-doc-face
for documentation strings in the code. This inherits, by default, from font-lock-string-face.

From the Gnu/Emacs page on font lock faces

I think it is fitting. Some themes might not implement a specific color for this face, and it will fallback to the string face (as it is now), but the semantics would be right; and the themes that has defined the face would be spot on.

[whatyouhide]

@gausby awesome catch, I say #justdoit with a PR 😃

[gausby]

@whatyouhide I would love to know how to do it, but it would require me to be able to distinct between multiline strings and actual docstrings so I can apply the font face to them. Perhaps I should pair with Tonini on this at some point.

[pdilyard]

Another possibility to consider here would be using markdown indentation rules within docstrings, so you wouldn't have to enter visual mode to manually move code blocks to the correct level.

[gausby]

I think that would be hard to implement; essentially it would require us to redo the stuff markdown mode does. It would probably be better to have a mode like mmm-mode (multi-major-mode) handle this, but the individual would have to set this up for themselves—an article on how to do this would be nice.

[tonini]

@gausby we should try your solution. 👍

[pdilyard]

Yes, an article on how to set it up would be very helpful

[pdilyard]

Has anyone attempted this yet? I'd love to look at grey docstrings 😄

I'd also be willing to try this myself if someone could point me in the right direction in the code.

[edmz]

@pdilyard I suck at elisp. Anyway, I tried using polymode to create a mode for only docstrings and then have a meta-mode that uses elixir-mode and this new mode at the same time. But then I ran into problems because font-lock-mode seems to come with default highlighting for strings and it took precenden over what I did. Anyway, I failed, just wanted to share the approach I tried.

[edmz]

(I want to apologize first to those who do know elisp. Hopefully what I've found is helpful)

OK, I had some time and researched this a bit.

I looked at how python-mode achieves this.

Elixir mode sets the value of font-lock-defaults the simpler way. There is a more verbose way to set that variable that allows more customization.

(set (make-local-variable 'font-lock-defaults)
     '(elixir-font-lock-keywords))

Python sets this variable in a more complex way:

(set (make-local-variable 'font-lock-defaults)
     '(python-font-lock-keywords
       nil nil nil nil
       (font-lock-syntactic-face-function
        . python-font-lock-syntactic-face-function)))

By doing it this way, it is able to specify a function for font-lock-syntactic-face-function.

Syntactic font locking allows:

Syntactic fontification uses a syntax table (see Syntax Tables) to
find and highlight syntactically relevant text. If enabled, it
runs prior to search-based fontification. The variable
font-lock-syntactic-face-function determines which syntactic
constructs to highlight.

This is, I think, ideal for this case.

The function that does this in python-mode is:

(defun python-font-lock-syntactic-face-function (state)
  "Return syntactic face given STATE."
  (if (nth 3 state)
      (if (python-info-docstring-p state)
          font-lock-doc-face
        font-lock-string-face)
    font-lock-comment-face))

That function has to decide the type of expression it is looking at.

We could basically copy this and just implement the equivalent python-info-docstring-p. It seems easy, but I choked trying.

Hopefully this helps other more knowledgeable people find a solution to this.

I will dump here some relevant links I found along the way:

https://www.gnu.org/software/emacs/manual/html_node/elisp/Font-Lock-Basics.html
https://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Parsing.html
https://emacs.stackexchange.com/questions/20712/how-to-add-complex-syntax-highlighting-in-a-minor-mode/20713
https://ftp.gnu.org/old-gnu/Manuals/elisp-manual-21-2.8/html_node/elisp_590.html
https://www.gnu.org/software/emacs/manual/html_node/elisp/Character-Motion.html

[edmz]

@pdilyard hopefully what I found ^^ helps you

[edmz]

@andreas-roehler man, I want to cry! 😆

[pdilyard]

Woah! Thanks @edmz and @andreas-roehler

[wpcarro]

Having difficulty getting this to work. When I run elixir-mode-version it seems to display the correct information:

Elixir-Mode version: 2.3.1 (package: 20170102.942)

However my @doc strings still use the font-lock for comments. Does anyone know why this may be? I uninstalled elixir-mode, ran package-refresh-contents, and reinstalled, but alas no positive results...

[edmz]

@wpcarro did you update from package.el? You might try closing the file and opening it again. Or change mode to fundamental then back again to elixir mode.

[wpcarro]

@edmz Just tried M-x fundamental-mode then M-x elixir-mode. No difference made. Repeated these steps after killing all Elixir buffers -- nothing. I've also restarted Emacs, without success.

How can I update from package.el? I may have already done so, but I'm unsure. Do you mind sharing your output from M-x elixir-mode-version?

[mattdeboard]

You are running the latest tagged version which is 9 months old or so which means you are installing the package from melpa-stable. This repo has pretty much stopped relying on melpa-stable, and just using melpa.

…

On Thu, Jan 12, 2017 at 10:16 AM, William Carroll ***@***.***> wrote: Just tried M-x fundamental-mode then M-x elixir-mode. No difference made. Repeated these steps after killing all Elixir buffers -- nothing. I've also restarted Emacs, without success. How can I update from package.el? I may have already done so, but I'm unsure. Do you mind sharing your output from M-x elixir-mode-version? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#355 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AASti22qtdUKNxxcC5JB9oPtRUsTuLBnks5rRlHcgaJpZM4IbVp4> .

[wpcarro]

@mattdeboard switched to Melpa (nonstable). Uninstalled elixir-mode and reinstalled. Still nothing. Is there a way that I can ensure that it uses the most up-to-date /master?

[pdilyard]

I can confirm that my elixir-mode (which I'm using in spacemacs) is at version 20170102.942, but this feature does not seem to be there (my docstrings are still yellow). Is it possible that this was just never a working change? Or am I still missing something?

[pdilyard]

I take that back, it works, it just isn't customized by the theme I was using.

The following applies to spacemacs users (and may also apply to pure emacs users, but I can't guarantee that):

For anyone who is having problems, try executing M-x configuration-layer/update-packages.

If you place your cursor over the documentation and run M-x describe-face, you should see font-lock-doc-face.

If you want to customize that part of your theme, you can place the following code (adjusted for your theme and the color you want) in your dotspacemacs/user-config function:

  (custom-theme-set-faces
   'molokai
   '(font-lock-doc-face ((t (:foreground "#465457")))))