Show all Scaladoc options

[som-snytt]

Demonstrate the styles of indentation without prejudice.

[olafurpg]

This does a good job of summarizing the three major conventions I've seen in the wild. It seems the "Scaladoc" style aligned by the first asterisk is used in projects like

• scala/scala: https://github.com/scala/scala/blob/21d12e9f5ec1ffe023f509848911476c1552d06f/src/library/scala/Predef.scala#L21
• Scala.js: https://github.com/scala-js/scala-js/blob/2bff6b49c1ab6b83984647d02b07540f45c1ab71/compiler/src/main/scala/org/scalajs/core/compiler/GenJSCode.scala#L27
• scalaceck: https://github.com/rickynils/scalacheck/blob/b00d40ec6db552545f7687d83e518d90e63424cc/src/main/scala/org/scalacheck/Prop.scala#L61

while the "Javadoc" style is used in libraries like

• Akka: https://github.com/akka/akka/blob/47045940d08c54eea190f522d9421dd38bee13da/akka-actor/src/main/scala/akka/actor/Actor.scala#L23
• ScalaTest: https://github.com/scalatest/scalatest/blob/a64b88a0c9576c5ffe19b673a1b3cfa48730f06b/scalatest/src/main/scala/org/scalatest/FlatSpec.scala#L21
• Cats: https://github.com/typelevel/cats/blob/923cc2161d61c73ca57ee1e334bd9f1fda7118b9/core/src/main/scala/cats/Monad.scala#L6
• Spark: https://github.com/apache/spark/blob/edcb878e2fbd0d85bf70614fed37f4cbf0caa95e/core/src/main/scala/org/apache/spark/rdd/RDD.scala#L49
• Fastparse: https://github.com/lihaoyi/fastparse/blob/dcb44cc0ec73d0d680bc29322afb47625316a68e/fastparse/shared/src/main/scala/fastparse/core/ParserApi.scala#L12

The third one is used by poor souls like myself who followed the old recommendations on the official style-guide.

[olafurpg]

s/ScaLadoc/Scaladoc/ ?

[eddsteel]

To fix the issue where tools/editors refer to "Scaladoc style", could these have names? I've seen flat and ragged used elsewhere. Thus your options could be "Javadoc", "Flat Scaladoc", "Ragged Scaladoc".

[olafurpg]

I totally agree @eddsteel, if the official guide will advertise three different styles then it should give each style a name. However, I think we should first try to see if we can agree on a single style first and avoid the need for coming up with three names. Let's continue this discussion in https://contributors.scala-lang.org/t/quiet-changes-to-the-style-guide/923/6

[SethTisue]

hey @som-snytt, rebase? and then let's get this merged. in the absence of any broader changes to how the style guide is managed, in the meantime we might as well merge this, it reflects the current status quo

[SethTisue]

thanks, A.P.!

[som-snytt]

@SethTisue N.P.