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

The "ScalaDoc" docstrings #891

Open
eed3si9n opened this Issue Apr 20, 2017 · 7 comments

Comments

3 participants
@eed3si9n
Contributor

eed3si9n commented Apr 20, 2017

Ref sbt/sbt#3125

  • Version: 0.6.8
  • Integration: sbt
  • Configuration:
maxColumn = 100

Scalafmt defaults to docstrings setting called ScalaDoc, which formats like:

/** Align by second asterisk.
  *
  */

and the other style is called JavaDoc.
Does the source of this recommendation come from http://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html? The name might be misleading since ScalaDoc will function normally with "JavaDoc" style.

It might be better to rename them to more neutral sounding styles (like FirstAsterisk and SecondAsterisk?) and default to what's currently called "JavaDoc".

@olafurpg

This comment has been minimized.

Show comment
Hide comment
@olafurpg

olafurpg Apr 20, 2017

Member

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

An alternative Scaladoc comment style right-aligns the column of asterisks under the second asterisk, in the third column. The Scaladoc tool also accepts Javadoc comment formatting, with text following the single asterisks, separated by a single space.

It might be worth to update that section since it indeed seems like the "javadoc" comment formatting is more conventional.

Member

olafurpg commented Apr 20, 2017

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

An alternative Scaladoc comment style right-aligns the column of asterisks under the second asterisk, in the third column. The Scaladoc tool also accepts Javadoc comment formatting, with text following the single asterisks, separated by a single space.

It might be worth to update that section since it indeed seems like the "javadoc" comment formatting is more conventional.

@olafurpg olafurpg modified the milestones: v0.7.0, v1.0 Apr 23, 2017

@olafurpg

This comment has been minimized.

Show comment
Hide comment
@olafurpg

olafurpg May 7, 2017

Member

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?

Member

olafurpg commented May 7, 2017

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?

@eed3si9n

This comment has been minimized.

Show comment
Hide comment
@eed3si9n

eed3si9n May 7, 2017

Contributor

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 &ldquo;behavior-driven&rdquo; 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.

Which is the right one?

Not sure if it's the matter of correctness, but in terms of JavaDoc tradition, skipping the first line is the right style.

Should scalafmt enforce either one?

Yes. I think it should.

Contributor

eed3si9n commented May 7, 2017

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 &ldquo;behavior-driven&rdquo; 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.

Which is the right one?

Not sure if it's the matter of correctness, but in terms of JavaDoc tradition, skipping the first line is the right style.

Should scalafmt enforce either one?

Yes. I think it should.

@olafurpg

This comment has been minimized.

Show comment
Hide comment
@olafurpg

olafurpg Jun 8, 2017

Member

I would like to get back to this one before v1, but I'm not sure what to do exactly. Are you proposing that scalafmt should enforce the first sentence to appear on the second line?

/** Kasbar
 * Foobar
 */

// INTO

/**
 * Kasbar
 * Foobar
 */
Member

olafurpg commented Jun 8, 2017

I would like to get back to this one before v1, but I'm not sure what to do exactly. Are you proposing that scalafmt should enforce the first sentence to appear on the second line?

/** Kasbar
 * Foobar
 */

// INTO

/**
 * Kasbar
 * Foobar
 */
@eed3si9n

This comment has been minimized.

Show comment
Hide comment
@eed3si9n

eed3si9n Jun 13, 2017

Contributor

I would like to get back to this one before v1, but I'm not sure what to do exactly. Are you proposing that scalafmt should enforce the first sentence to appear on the second line?

Yes. Keeping the first line blank seems to be the tradition carried over from Javadoc, adopted by Cats, ScalaTest, Akka, and sbt.

Contributor

eed3si9n commented Jun 13, 2017

I would like to get back to this one before v1, but I'm not sure what to do exactly. Are you proposing that scalafmt should enforce the first sentence to appear on the second line?

Yes. Keeping the first line blank seems to be the tradition carried over from Javadoc, adopted by Cats, ScalaTest, Akka, and sbt.

@olafurpg

This comment has been minimized.

Show comment
Hide comment
@magnolia-k

This comment has been minimized.

Show comment
Hide comment
@magnolia-k

magnolia-k Oct 6, 2018

The current Scaladoc style guide describes the style of comment as follows and it is not written to suggest any one.

https://docs.scala-lang.org/style/scaladoc.html

The Scaladoc tool does not mandate a documentation comment style.

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)

magnolia-k commented Oct 6, 2018

The current Scaladoc style guide describes the style of comment as follows and it is not written to suggest any one.

https://docs.scala-lang.org/style/scaladoc.html

The Scaladoc tool does not mandate a documentation comment style.

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)

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