DocGen generating JavaDoc style, not ScalaDoc style comments

[julianpeeters]

Hi again,

I notice that treehugger produces JavaDoc style when I believe the intent is to produce ScalaDoc style. [Treehugger's documentation] shows the issue: (http://eed3si9n.com/treehugger/comments.html#Scaladoc+style+comments), while here is the ScalaDoc spec.

The differences that ScalaDoc adopts seem to be: 1) Text always begins on the first line, after /* 2) ""s that begin new comment lines in multiline comments should be aligned in the 3rd column rather than the second.

Not really sure this is a pressing issue. I'd suspect that JavaDoc style is pretty compatible with most ScalaDoc parsers (?). Also, it appears that intellij seems to have the same issue (using JavaDoc style for ScalaDocs), and that doesn't seem to cause much trouble.

So not really an issue for me, but I thought I should report this.

[eed3si9n]

Thanks for the report.

[eed3si9n]

+1 on fixing this. I'd accept PR for this if you're up for it.

[julianpeeters]

Yup, I'll take a swing.

[eed3si9n]

I've since then looked into the ScalaDoc styling, and came to conclusion that "JavaDoc" style should be the standard. See https://github.com/scalameta/scalafmt/issues/891

• Style Guide http://docs.scala-lang.org/style/scaladoc.html recommends the "JavaDoc" style.
• Many of the OSS projects use the "JavaDoc" style. Here are some random sampling:
  • https://github.com/scala/scala/blob/v2.12.2/src/library/scala/Predef.scala
  • https://github.com/akka/akka/blob/v2.5.0/akka-actor/src/main/scala/akka/actor/Actor.scala
  • https://github.com/scalatest/scalatest/blob/release-3.0.2/scalatest/src/main/scala/org/scalatest/FlatSpec.scala
  • https://github.com/typelevel/cats/blob/v0.9.0/core/src/main/scala/cats/Monad.scala

[julianpeeters]

:+1:

[eed3si9n]

Closing this.