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.

[smarter]

The reality is people will keep cross-compiling with Scala 2 and relying on the Scala 2 scaladoc for a long time, so the more we do to make it easier to accommodate both syntaxes without needing compiler flags or magic annotations in comments the better, or is there some technical reason that prevents us from supporting {{{ ... }}} by default?

[lrytz]

FWIW, I agree with @smarter. I believe Scala 3 tools should by default work for any Scala 2 code, unless there are strong technical reasons that don't allow it. People working on dotc are going a really, really long ways to ensure this (#11603 is a recent example), and I don't see a reason why it should be different for Scaladoc. Everything that reduces friction for the migration is a good thing.

[abgruszecki]

I guess we could add a hybrid syntax and enable it by default? I guess that helps to some extent with migration/coexistence, since what people seem to mostly use is lists, code blocks, monospaces and links? All other Wiki syntax elements wouldn't work, and they, unlike Markdown syntax, look ugly if not rendered.

I still would prefer having either strict Wiki or strict Markdown for any codebase I work with, though.

[smarter]

I guess we could add a hybrid syntax and enable it by default?

That's what I had in mind yes, especially since the default is already hybrid since it supports wiki links: https://dotty.epfl.ch/docs/usage/scaladoc/docComments.html

[abgruszecki]

Wiki links are a different thing, there was just no way to fit the syntax for them into Markdown links.

I'm still quite unsure about those code blocks. On one hand, the "hybrid" syntax is 80% compatible with old Wiki syntax, and it could also be used whenever we're unsure what syntax a comment is in (consider, say, the REPL); on another hand, I have no idea whether those code blocks should be allowed in standalone Markdown, and how they're supposed to interact with planned features like code playgrounds (which should know the language a code block is in).

[smarter]

like with markdown code block, we should default to assume the code block language is Scala.

[abgruszecki]

I guess we may not actually want to turn code playground for anything that isn't specifically designated to be interactive? I guess that most code blocks in the wild aren't actually valid standalone code, and so we may not want to break them?

[abgruszecki]

Funnily enough, I think if we enable hybrid by default, we may actually fix some preexisting documentation. The docs for cats here have a list that is correct Markdown, but not correct Wiki; I've seen Markdown _underscore_ syntax used in docs for Zio as well.

[abgruszecki]

So! Markdown syntax was actually extended with {{{ … }}} syntax in #11833, so this issue can be closed.