The Scaladoc {{{...}}} code block syntax isn’t working

[alvinj]

Compiler version

3.0.0-RC1, as well as the latest nightly build

Minimized code

/**
  * Specify the `name`, `age`, and `weight` when creating a new `Person`,
  * then access the fields like this:
  *
  * {{{
  * val p = Person("Al", 42, 200.0)
  * p.name
  * p.age
  * p.weight
  * }}}
  *
class Person (var name: String, var age: Int, var weight: Double)

Output

The {{{...}}} text shows up in the Scaladoc, like this:

... the fields like this: {{{ val p = Person("Al", 42, 200.0) p.name p.age p.weight }}}

Expectation

I expected the code in the {{{...}}} block to be displayed as multiple lines of PRE/CODE text in the resulting Scaladoc, like this:

val p = Person("Al", 42, 200.0)
p.name
p.age
p.weight

[abgruszecki]

@alvinj Scaladoc now uses Markdown syntax by default. You can change the default with a CLI flag, or you could force Wiki syntax for a particular comment by adding @syntax wiki to it (adding it at the end will work). Does that help?

[Katrix]

Doesn't this break backwards compatibility when cross compiling older sources?

[abgruszecki]

@Katrix in what sense? I guess if one wants to generate docs for each language version, the comments need to be in Wiki syntax, otherwise it's possible to only use the latest version and use the Md syntax, no?

[smarter]

Would it be possible to support the old code blocks by default just like the wiki link syntax is supported by default? (cf https://dotty.epfl.ch/docs/usage/scaladoc/docComments.html, and related discussion in #11612)

[alvinj]

Scaladoc now uses Markdown syntax by default.

@abgruszecki Thanks! I read through the Scala3doc Contributors post and put a question on Gitter, but I didn’t know for sure what tags were supported. I’ll give Markdown a try! 👍

[abgruszecki]

@smarter we could consider that, though I'm not 100% convinced that polluting the Markdown syntax with Wiki just for migration purposes is worth it. We could also try to put together a tool that will automatically rewrite the comments from Wiki to Markdown. I guess the situation isn't too bad, since it's always possible to just keep on using Wiki syntax by default, i.e. we don't need absolutely to have that tool ready by release.

[smarter]

we could consider that, though I'm not 100% convinced that polluting the Markdown syntax with Wiki just for migration purposes is worth it.

I think that supporting at least the {{{ ... }}} by default has the right cost/benefit ratio: it means a lot of existing documentation can work as-is, and it shouldn't break anything because it's not something that would appear naturally in markdown comments. Also we avoid headaches with mixed syntaxes like in #11674 where even if we could say "the scala package uses wiki syntax" we run into trouble because dotty defines stuff in the scala package.

[abgruszecki]

The way I see it, what codebases migrating from Scala2 should do is that they should set the default syntax to Wiki, and update comments one-by-one, when they are touched. I'm not sure how adding hybrid syntax helps with that. I'm not sure either what is the problem in the PR you linked - if desired, one can enable Markdown syntax for those specific comments by adding @syntax markdown to them.