Fix markdown syntax for scala3 library docstrings

[BarkingBad]

Before

After

[BarkingBad]

There might be more docstrings that need @syntax markdown applied

[smarter]

I don't understand this change, doesn't scaladoc use markdown syntax by default? We certainly want to use it by default for all new code, having to add @syntax markdown everywhere would be very cumbersome.

[BarkingBad]

Well, scaladoc uses markdown syntax by default. However, most of the compiler has comments with wikisyntax. Therefore, we run scaladoc with wikisyntax flag raised. We could either:

• convert everything to markdown (a lot of work, since most of the comments are already in wikisyntax)
• convert everything to wikisyntax
• add markdown syntax annotation

The third option was the easiest as I didn't have to rewrite all the conflicting symbols.

[smarter]

most of the compiler has comments with wikisyntax.

Do you have examples? From what I can see, most of the comments use markdown syntax (backticks for code are very commonly used for example).

Also, can't we support using both syntaxes at once?

[BarkingBad]

Just browsed the .scala files for occurances of \*.*\{\{\{|\*.*\[\[ regex which I believe is correct ([[ and {{{ are known for wikisyntax) and got 2534 occurances across 569 files. I see markdown is also present (```) has 308 results in 42 files, but I fixed it for these docstrings that are in public api of dotty compiler.

[BarkingBad]

As for supporting both syntaxes, it is hard as we should have to assume whether something is in markdown or wikisyntax, which I think we cannot so easily determine.

[smarter]

[[ and {{{ are known for wikisyntax)

[[ is supported under markdown syntax according to http://dotty.epfl.ch/docs/usage/scaladoc/docComments.html

Limiting myself to {{{ and searching in all the source code in the dotty repo I get:

% rg -o '\*.*\{\{\{' library compiler interfaces scaladoc tasty-inspector staging language-server|wc -l
68

Am I missing something? Perhaps you're also looking at the scala 2 standard library scala files, but that's a different project (and this one does use wiki syntax since it has to work with the scala 2 scaladoc too).

[BarkingBad]

Yes, you are right. However I thought we want to have wikisyntax as a default for compiler.

So what do you propose? Certainly we have to revert these changes, but should we update the old comments with @syntax wiki or actually rewrite all these comments to be in markdown style?

[smarter]

I think ideally we should support wiki code blocks by default if possible: #11728 (comment), otherwise I would prefer to default to markdown syntax and rewrite comments (maybe we can do that with a regexp to replace {{{ and }}} by three backticks).

[BarkingBad]

I talked with @romanowski and he told me we document a lot of scala2 code in our projects which has wikisyntax docstrings. Maybe the best solution is to remove flag -comment-syntax wiki and introduce new flag that will list all directories that are supposed to be documented in wikisyntax using regex prefixes. Similar mechanism is already implemented for skipping packages, so it would be easy and convenient, moreover we won't interfere with exisiting docstrings. This solution is also useful for library developers migrating to scala3 that have some old scala2 code with wikisyntax.