scala / scala3

The Scala 3 compiler, also known as Dotty.
https://dotty.epfl.ch
Apache License 2.0
5.88k stars 1.06k forks source link

Scaladoc <code> tags recursively applied after code in markdown comment #11477

Closed KacperFKorban closed 3 years ago

KacperFKorban commented 3 years ago

Description of method has a recursively applied <code> tag after the markdown code is ended, which results in a really small text. e.g. (https://github.com/lampepfl/dotty/blob/master/library/src/scala/compiletime/package.scala)

 /** Use this method when you have a type, do not have a value for it but want to
   *  pattern match on it. For example, given a type `Tup <: Tuple`, one can
   *  pattern-match on it as follows:
   *  ```
   *  inline erasedValue[Tup] match {
   *    case _: EmptyTuple => ...
   *    case _: h *: t => ...
   *  }
   *  ```
   *  This value can only be used in an inline match and the value cannot be used in
   *  the branches.
   */
  erased def erasedValue[T]: T = ???

results in this entry: image https://dotty.epfl.ch/api/scala/compiletime.html#erasedValue-fffff7c4

BarkingBad commented 3 years ago

The problem is in default syntax. The default syntax for stdlib libraries is WikiSyntax, yet somebody used markdown grammar, which breaks the layout. We should either normalize everything to WikiSyntax, or annotated these docs with explicit markdown syntax.