Skip to content

Scaladoc wrongly interprets markdown inside code blocks #12868

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ShapelessCat opened this issue Jun 18, 2021 · 3 comments · Fixed by #12887
Closed

Scaladoc wrongly interprets markdown inside code blocks #12868

ShapelessCat opened this issue Jun 18, 2021 · 3 comments · Fixed by #12887

Comments

@ShapelessCat
Copy link
Contributor

ShapelessCat commented Jun 18, 2021

The section "Types supporting derives clauses" of the document Type Class Derivation includes a code example

```scala
sealed trait Mirror:

  /** the type being mirrored */
  type MirroredType

  /** the type of the elements of the mirrored type */
  type MirroredElemTypes

  /** The mirrored *-type */
  type MirroredMonoType

  /** The name of the type */
  type MirroredLabel <: String

  /** The names of the elements of the type */
  type MirroredElemLabels <: Tuple
```

Currently its view in HTML is wrong: several lines are merged into one line.
I guess the reason is the *-type, the comment line that above the code type MirroredMonoType, which affects the HTML rendering.

Please check http://dotty.epfl.ch/docs/reference/contextual/derivation.html
I already checked its view in both Chrome and Firefox.

@ShapelessCat ShapelessCat changed the title The Wrong View of A Code Example in The Document "Type Class Derivation" The Wrong HTML View of A Code Example in The Document "Type Class Derivation" Jun 19, 2021
@smarter smarter changed the title The Wrong HTML View of A Code Example in The Document "Type Class Derivation" Scaladoc wrongly interprets markdown inside code blocks Jun 19, 2021
@pikinier20 pikinier20 self-assigned this Jun 21, 2021
@ShapelessCat
Copy link
Contributor Author

ShapelessCat commented Jun 23, 2021

@pikinier20
I think your #12887 fixed the bug I mentioned, but it also introduced a new bug.
You can check the same code example, the companion object part:

object Mirror:

  /** The Mirror for a product type */
  trait Product extends Mirror:

    /** Create a new instance of type `T` with elements * taken from product `p`. */ 
    def fromProduct(p: scala.Product): MirroredMonoType

  trait Sum extends Mirror:

    /** The ordinal number of the case class of `x`. * For enums, `ordinal(x) == x.ordinal` */ 
    def ordinal(x: MirroredMonoType): Int

end Mirror

The last two comments should be multiple line comments. You can see those *s, which should be at the beginning of new lines, now in the middle of those single line comments.

@pikinier20
Copy link
Contributor

It seems like it's another unrelated bug inside our hljs rules. It will be hard to decide whether * is start of emphasis or newline (eg. if there would be two *'s). Hljs may be not sophisticated enough to be able to fix this, but I'm gonna think about this.

@TheElectronWill
Copy link
Contributor

TheElectronWill commented Jun 23, 2021

Is it really because of this rule? I don't get the multiline problem if I use my test + this commit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants