Syntax highlighting for @doc, @moduledoc and @typedoc can be a bit distracting

[doughsay]

With the recent addition of Markdown syntax highlighting for @doc, @moduledoc and @typedoc (#90) it makes scanning code a bit harder, because large documentation blocks have the same default text color and syntax highlighting colors as the actual code.

Comparing it to how other languages do documentation highlighting (for example TSDoc in TypeScript files), we see that they at least use the default comment color as the default text color, making it easier to identify blocks of documentation vs blocks of code.

Expected behavior

I'd love it if we could keep the markdown highlighting / language awareness, but change the default text color to match comments. I know this might not be possible, or might be hard, but that (I think) would be the ideal solution.

Example screenshots

With Markdown syntax highlighting, it's harder to quickly scan the code and distinguish documentation blocks from code blocks:

Without Markdown highlighting (this is ElixirLS's vscode extension, so the colors are different):

Example of TypeScript, showing the default color being the comment color:

[lucavenir]

My two cents: I think I prefer the comment color better. Furthermore, the typescript example is even more noisy imho, I don't feel like that's a "middle ground".

To me it's hard to distinguish between examples, docs and actual code; I think this will be especially true if you're even a tiny bit neurodivergent (e.g. dysgraphia/dyslexia).

Maybe a third way would be to toggle this setting in lexical's settings?

[objectuser]

So far, when editing a file with a comment containing markdown, I don't find it useful to have the markdown contents highlighted there. For me, the purpose is to get useful when using the module/function (through the hover popup). It's more noisy than useful when editing the file itself.

[Blond11516]

Thanks to you three for your input!

I agree the current solution isn't ideal. Making it configurable sadly isn't easy to I think do because grammars are statically defined in JSON files, so they can't be affected by settings.

I'll have to research if

1. It's possible to define or "load" a grammar in code, which would allow user configuration
2. There's a way to change the default text color for the embedded markdown. Off the top of my head I'm not sure it is possible but I'll try to find similar situations in other languages and see how they handle this.

I might not have a lot of time to work on this soon though, so I might end up reverting the change since I agree the current highlighting is very distracting.

[Terbium-135]

I'd say revert the change for now until we find a better solution (if any at all) so people have the developer experience they are used to

[Blond11516]

I've reverted the markdown syntax highlighting and published a new version.

I'll close this issue. @Terbium-135 feel free to open a new issue or PR if you want to revisit this, I'll be happy to review it, but I personally won't be spending too much time researching this in the foreseeable future.