Join GitHub today
The "ScalaDoc" docstrings #891
Scalafmt defaults to docstrings setting called
/** Align by second asterisk. * */
and the other style is called
It might be better to rename them to more neutral sounding styles (like FirstAsterisk and SecondAsterisk?) and default to what's currently called "JavaDoc".
Thank you for opening this detailed issue. I agree that JavaDoc/ScalaDoc may be confusing names, I'm in favor of adopting more neutral names and switch the default to the current "javadoc" setting.
The reasoning behind the current names comes from here: http://docs.scala-lang.org/style/scaladoc most notably
It might be worth to update that section since it indeed seems like the "javadoc" comment formatting is more conventional.
I see that the scala style guide uses a single space indent for the top line and 2 space indent when aligning by the first asterisk
/** Kasbar * Foobar */
scala/scala does the same. However, cats/scalatest/akka use single space indent for the non-header lines
/** Kasbar * Foobar */
Which is the right one? Should scalafmt enforce either one?
Good catch. Javadoc burns the first line, and not use it. See List.java:
/** * An ordered collection (also known as a <i>sequence</i>). The user of this * interface has precise control over where in the list each element is * inserted. The user can access elements by their integer index (position in * the list), and search for elements in the list.<p> ...
Cats, ScalaTest, and Akka are following the style consistently:
/** * Monad. * ...
/** * Marker trait to signal that this class should not be verified for serializability. */
/** * Facilitates a “behavior-driven” style of development (BDD), in which tests * ...
Count sbt too in the camp:
/** * The API for the source file `src` at the time represented by this instance. * This method returns an empty API if the file had no API or is not known to this instance. */
So it's actually, and scala/scala is the odd one out here (Edit: I edited the example below):
/** The `Predef` object provides definitions that are accessible in all Scala * compilation units without explicit qualification.
Not sure if it's the matter of correctness, but in terms of JavaDoc tradition, skipping the first line is the right style.
Yes. I think it should.
Yes. Keeping the first line blank seems to be the tradition carried over from Javadoc, adopted by Cats, ScalaTest, Akka, and sbt.
Related discussion https://contributors.scala-lang.org/t/quiet-changes-to-the-style-guide/923/7
referenced this issue
Aug 8, 2017
The current Scaladoc style guide describes the style of comment as follows and it is not written to suggest any one.
Therefore, it is necessary to discuss which mode should be the default mode, but should support at least three styles stated in the style guide and should also match the mode name?
(Since the name is descriptive and too long, it is necessary to think a little short mode name)