diff --git a/style/scaladoc.md b/style/scaladoc.md
index 80541848f4..f153f7ce68 100644
--- a/style/scaladoc.md
+++ b/style/scaladoc.md
@@ -22,21 +22,29 @@ 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 = {}
 
+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 = {}
 
-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)
@@ -100,23 +108,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 +146,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 +169,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 +189,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