From f71228de7b609abf2c500f7378db27d461b96e12 Mon Sep 17 00:00:00 2001 From: Som Snytt Date: Sat, 30 Jul 2016 02:18:00 -0700 Subject: [PATCH 1/3] Swap star-space for space-star Everyone is confused why the style page recommends the odd column for asterisks. --- style/scaladoc.md | 84 +++++++++++++++++++++++------------------------ 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/style/scaladoc.md b/style/scaladoc.md index 80541848f4..5083f9593c 100644 --- a/style/scaladoc.md +++ b/style/scaladoc.md @@ -22,10 +22,10 @@ experienced users, but can be invaluable for newcomers). The general format for a Scaladoc comment should be as follows: /** This is a brief description of what's being documented. - * - * This is further documentation of what we're documenting. It should - * provide more details as to how this works and what it does. - */ + * + * This is further documentation of what we're documenting. It should + * provide more details as to how this works and what it does. + */ def myMethod = {} For methods and other type members where the only documentation needed @@ -100,23 +100,23 @@ notation: package my.package /** Provides classes for dealing with complex numbers. Also provides - * implicits for converting to and from `Int`. - * - * ==Overview== - * The main class to use is [[my.package.complex.Complex]], as so - * {{ "{{{" }} - * scala> val complex = Complex(4,3) - * complex: my.package.complex.Complex = 4 + 3i - * }}} - * - * If you include [[my.package.complex.ComplexConversions]], you can - * convert numbers more directly - * {{ "{{{" }} - * scala> import my.package.complex.ComplexConversions._ - * scala> val complex = 4 + 3.i - * complex: my.package.complex.Complex = 4 + 3i - * }}} - */ + * implicits for converting to and from `Int`. + * + * ==Overview== + * The main class to use is [[my.package.complex.Complex]], as so + * {{ "{{{" }} + * scala> val complex = Complex(4,3) + * complex: my.package.complex.Complex = 4 + 3i + * }}} + * + * If you include [[my.package.complex.ComplexConversions]], you can + * convert numbers more directly + * {{ "{{{" }} + * scala> import my.package.complex.ComplexConversions._ + * scala> val complex = 4 + 3.i + * complex: my.package.complex.Complex = 4 + 3i + * }}} + */ package complex {} ## Classes, Objects, and Traits @@ -138,11 +138,11 @@ If the class should be created using a constructor, document it using the `@constructor` syntax: /** A person who uses our application. - * - * @constructor create a new person with a name and age. - * @param name the person's name - * @param age the person's age in years - */ + * + * @constructor create a new person with a name and age. + * @param name the person's name + * @param age the person's age in years + */ class Person(name: String, age: Int) { } @@ -161,19 +161,19 @@ sure to indicate the actual method names: /** Factory for [[mypackage.Person]] instances. */ object Person { /** Creates a person with a given name and age. - * - * @param name their name - * @param age the age of the person to create - */ + * + * @param name their name + * @param age the age of the person to create + */ def apply(name: String, age: Int) = {} /** Creates a person with a given name and birthdate - * - * @param name their name - * @param birthDate the person's birthdate - * @return a new Person instance with the age determined by the - * birthdate and current date. - */ + * + * @param name their name + * @param birthDate the person's birthdate + * @return a new Person instance with the age determined by the + * birthdate and current date. + */ def apply(name: String, birthDate: java.util.Date) = {} } @@ -181,12 +181,12 @@ If your object holds implicit conversions, provide an example in the Scaladoc: /** Implicit conversions and helpers for [[mypackage.Complex]] instances. - * - * {{ "{{{" }} - * import ComplexImplicits._ - * val c: Complex = 4 + 3.i - * }}} - */ + * + * {{ "{{{" }} + * import ComplexImplicits._ + * val c: Complex = 4 + 3.i + * }}} + */ object ComplexImplicits {} #### Traits From 90fb309ded99a29ec76b75719b75d4a4a7d567b1 Mon Sep 17 00:00:00 2001 From: Som Snytt Date: Sat, 30 Jul 2016 02:31:04 -0700 Subject: [PATCH 2/3] Third column is a fifth column. --- style/scaladoc.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/style/scaladoc.md b/style/scaladoc.md index 5083f9593c..88b3fb3522 100644 --- a/style/scaladoc.md +++ b/style/scaladoc.md @@ -34,9 +34,10 @@ is a simple, short description, this format can be used: /** Does something very simple */ def simple = {} -Note, especially for those coming from Java, that the left-hand margin -of asterisks falls under the \_third\_ column, not the second, as is -customary in Java. +Note that, in contrast to the Javadoc convention, the text begins +on the first line of the comment but that subsequent text remains aligned. +In particular, text is aligned on a multiple of two columns, +since Scala source is usually indented by two columns. See the [AuthorDocs](https://wiki.scala-lang.org/display/SW/Writing+Documentation) From 2aceb33952b79285c97e5392a7b335af9a5c5117 Mon Sep 17 00:00:00 2001 From: Som Snytt Date: Mon, 1 Aug 2016 10:47:59 -0700 Subject: [PATCH 3/3] Mention the plethora of comment styles. --- style/scaladoc.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/style/scaladoc.md b/style/scaladoc.md index 88b3fb3522..f153f7ce68 100644 --- a/style/scaladoc.md +++ b/style/scaladoc.md @@ -28,8 +28,15 @@ The general format for a Scaladoc comment should be as follows: */ def myMethod = {} +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. +Because the comment markup is sensitive to whitespace, +the tool must be able to infer the left margin. + For methods and other type members where the only documentation needed -is a simple, short description, this format can be used: +is a simple, short description, a one-line format can be used: /** Does something very simple */ def simple = {}