Highlight module and function docstrings as comments

[KornelH]

Set the syntax highlight to module and function documentation, more precisely to the docstring content of -moduledoc and -doc attributes to comment.

This change distinguish documentation comments and source code, just as the old EDoc comments did, and as other languages do as well, for example Elixir.

For more info, please check PR #9.

An additional change also included in the branch of this PR, highlight io:fread and io:fwrite control sequences in verbatim strings for convenience.

[robertoaloi]

Thanks for this @KornelH , let me test this a bit and come back to you!

[robertoaloi]

Hi @KornelH, I finally got a chance to try this locally. First, let me say that the change is very welcome, since big docstrings can indeed be confusing.

One thing I noticed is that the change is quite sensitive to formatting. For example, it doesn't work if there's a newline after a fun. Compare the two following snippets:

Also, are there any plans about the -doc metadata? Right now they look like generic terms. This last point does not block the PR, since things can be improved incrementally, I'm just curious about your thoughts.

[KornelH]

Hi @robertoaloi,

I start with the second note, I didn't plan to do anything with -doc metadata attributes. Usually, it's just one line if present at all, so I don't mind to have the regular syntax for that.

Regarding the first note, I know about this issue but it is not related to the current or earlier docstring changes. It's an old standing problem in function expression syntax highlighting that is sensitive for formatting and breaks the following attributes. Before OTP 27 it was usually noticeable on -define attributes:

[robertoaloi]

Regarding the first note, I know about this issue but it is not related to the current or earlier docstring changes. It's an old standing problem in function expression syntax highlighting that is sensitive for formatting and breaks the following attributes. Before OTP 27 it was usually noticeable on -define attributes:

Ah, fair enough. I didn't notice that before. Thanks for pointing that out, let's create an issue for that.

I start with the second note, I didn't plan to do anything with -doc metadata attributes. Usually, it's just one line if present at all, so I don't mind to have the regular syntax for that.

That's all right, we can tweak this as a follow-up. Just for reference, in ELP we are converting the old @param Edoc tags into doc metadata, so they can be used for IDE features such as signature help. That can cause the -doc metadata to be non trivial. For example:

-doc #{params => #{"Foo" => "This is foo", "Bar" => "This is bar"}}.

[robertoaloi]

Thanks again for contributing this! 🎸

[robertoaloi]

Let's create an issue for that.

And there's already one: #1

[KornelH]

Yesterday, I looked into what VSC thinks about tokens when the syntax highlight is broken and it is the implicit function expressions (fun m:f/a) that are actually broken. The line break after fun is the culprit that activates implicit function expression until the next / sign that could be the arity divider. Since in the example there is no / sign, the syntax highlight is broken in the rest of the file.

Difference: 42 vs 42/1