Fix scaladoc for elements broken in scalameta#2700

Author: kitbellew

readme/src/main/scala/org/scalafmt/readme/Readme.scala

@@ -43,7 +43,11 @@ object Readme {
 
   /** repl session, inspired by tut.
     *
-    * Example: code="1 + 1" returns "scala> 1 + 1 res0: Int = 2"
+    * Example: {{{code="1 + 1"}}} returns
+    * {{{
+    *   scala> 1 + 1
+    *   res0: Int = 2
+    * }}}
     */
   def repl(code: String) = {
     import scala.meta._

scalafmt-cli/src/main/scala/org/scalafmt/cli/CliOptions.scala

@@ -17,8 +17,8 @@ object CliOptions {
   /** Tries to read configuration from
     *
     *   1. .scalafmt.conf in root dir of current git repo IF the following
-    *      setting is enabled: project.git = true 2. .scalafmt.conf from
-    *      init.common.workingDirectory
+    *      setting is enabled: project.git = true
+    *   1. .scalafmt.conf from init.common.workingDirectory
     *
     * I am happy to add alternative fallback methods for other VCS.
     *

scalafmt-cli/src/main/scala/org/scalafmt/cli/TermDisplay.scala

@@ -55,8 +55,9 @@ object Terminal {
 
     /** Clear the current line
       *
-      * n=0: clear from cursor to end of line n=1: clear from cursor to start of
-      * line n=2: clear entire line
+      *   - n=0: clear from cursor to end of line
+      *   - n=1: clear from cursor to start of line
+      *   - n=2: clear entire line
       */
     def clearLine(n: Int): Unit = control(n, 'K')
   }

scalafmt-cli/src/main/scala/org/scalafmt/cli/WriteMode.scala

@@ -2,8 +2,9 @@ package org.scalafmt.cli
 
 /** Determines the mode in which Scalafmt will behave
   *
-  * Override = Replace the file with its formatted form Stdout = Print the
-  * formatted file to Stdout (leaving the original file untouched)
+  *   - Override: Replace the file with its formatted form
+  *   - Stdout: Print the formatted file to Stdout (leaving the original file
+  *     untouched)
   */
 sealed trait WriteMode
 

scalafmt-core/shared/src/main/scala/org/scalafmt/config/Align.scala

@@ -7,48 +7,54 @@ import metaconfig.generic.Surface
 /** @param openParenCallSite
   *   If true AND bin-packing is true, then call-site arguments won't be aligned
   *   by the opening parenthesis. For example, this output will be disallowed
-  *
-  * function(a, b, c)
+  * {{{
+  *   function1(a,
+  *             b,
+  *             c)
+  * }}}
   * @param openParenDefnSite
   *   Same as [[openParenCallSite]], except definition site.
   * @param tokens
   *   The tokens to vertically align by. The "owner" is the
   *   scala.meta.Tree.getClass.getName of the deepest tree node that "owns" the
   *   token to align by.
+  *   - Examples:
+  * {{{
+  *   align.tokens = ["="] // align = owned by any tree node (not recommended)
   *
-  * Examples:
-  *
-  * align.tokens = ["="] // align = owned by any tree node (not recommended)
-  *
-  * align.tokens = [ { code = "=", owner = "Param" } // align = when owned by
-  * parameter tree nodes ]
-  *
-  * Pro tip. if you use for example
-  *
-  * preset = defaultWithAlign
-  *
-  * and want to add one extra token (for example "|>") to align by, write
-  *
-  * align.tokens."+" = [ "|> ]
-  *
-  * NOTE. Adding more alignment tokens may potentially decrease the vertical
-  * alignment in formatted output. Customize at your own risk, I recommend you
-  * try and stick to the default settings.
+  *   align.tokens = [
+  *     { code = "=", owner = "Param" } // align = when owned by parameter tree nodes
+  *   ]
+  * }}}
+  *   - Pro tip. if you use for example {{{preset = defaultWithAlign}}} and want
+  *     to add one extra token (for example "|>") to align by, write
+  * {{{
+  *     align.tokens."+" = [ "|> ]
+  * }}}
+  *   - NOTE. Adding more alignment tokens may potentially decrease the vertical
+  *     alignment in formatted output. Customize at your own risk, I recommend
+  *     you try and stick to the default settings.
   * @param arrowEnumeratorGenerator
   *   If true, aligns by `<-` in for comprehensions.
   * @param openParenCtrlSite
   *   If true, aligns by ( in if/while/for. If false, indents by continuation
   *   indent at call site.
   * @param tokenCategory
   *   Customize which token kinds can align together. By default, only tokens
-  *   with the same `Token.productPrefix` align. To for example align = and <-,
-  *   set the values to: Map("Equals" -> "Assign", "LeftArrow" -> "Assign")
-  *   Note. Requires mixedTokens to be true.
+  *   with the same `Token.productPrefix` align. For example, to align = and <-,
+  *   set the values to:
+  * {{{
+  *     Map("Equals" -> "Assign", "LeftArrow" -> "Assign")
+  * }}}
+  * Note: Requires mixedTokens to be true.
   * @param treeCategory
   *   Customize which tree kinds can align together. By default, only trees with
-  *   the same `Tree.productPrefix` align. To for example align Defn.Val and
-  *   Defn.Var, set the values to: Map("Defn.Var" -> "Assign", "Defn.Val" ->
-  *   "Assign") Note. Requires mixedOwners to be true.
+  *   the same `Tree.productPrefix` align. For example, to align Defn.Val and
+  *   Defn.Var, set the values to:
+  * {{{
+  *     Map("Defn.Var" -> "Assign", "Defn.Val" -> "Assign")
+  * }}}
+  * Note. Requires mixedOwners to be true.
   * @param stripMargin
   *   If set, indent lines with a strip-margin character in a multiline string
   *   constant relative to the opening quotes (or the strip-margin character if

scalafmt-core/shared/src/main/scala/org/scalafmt/config/Newlines.scala

@@ -80,7 +80,13 @@ import metaconfig.generic.Surface
   * }}}
   * @param alwaysBeforeElseAfterCurlyIf
   *   if true, add a new line between the end of a curly if and the following
-  *   else. For example if(someCond) { // ... } else //...
+  *   else. For example
+  * {{{
+  *   if(someCond) {
+  *     // ...
+  *   }
+  *   else //...
+  * }}}
   * @param beforeMultilineDef
   *   If unfold (or true), add a newline before the body of a multiline def
   *   without curly braces. See #1126 for discussion. For example,
@@ -114,15 +120,16 @@ import metaconfig.generic.Surface
   *       }
   * }}}
   * @param source
-  *   Controls how line breaks in the input source are handled If `classic`
-  *   (default), the old mixed behaviour will be used If `keep`, try to keep
-  *   source newlines If `fold`, ignore source and try to remove line breaks If
-  *   `unfold`, ignore source and try to break lines
+  *   Controls how line breaks in the input source are handled
+  *   - If `classic` (default), the old mixed behaviour will be used
+  *   - If `keep`, try to keep source newlines
+  *   - If `fold`, ignore source and try to remove line breaks
+  *   - If `unfold`, ignore source and try to break lines
   * @param afterInfix
-  *   Controls how line breaks around operations are handled If `keep` (default
-  *   for source=classic,keep), preserve existing If `some` (default for
-  *   source=fold), break after some infix ops If `many` (default for
-  *   source=unfold), break after many infix ops
+  *   Controls how line breaks around operations are handled
+  *   - If `keep` (default for source=classic,keep), preserve existing
+  *   - If `some` (default for source=fold), break after some infix ops
+  *   - If `many` (default for source=unfold), break after many infix ops
   * @param afterInfixBreakOnNested
   *   Force breaks around nested (enclosed in parentheses) expressions
   * @param afterInfixMaxCountPerFile

scalafmt-core/shared/src/main/scala/org/scalafmt/config/OptIn.scala

@@ -118,11 +118,12 @@ case class OptIn(
   /** See https://github.com/scalameta/scalafmt/issues/1712
     *
     * Setting behavior and name were mirrored. After deprecation and right
-    * naming we need to: if `forceBlankLineBeforeDocstring` (new name) has
-    * default value (true) fallback to `blankLineBeforeDocstring` (old config)
-    * which may be configured in .scalafmt.conf if
-    * `forceBlankLineBeforeDocstring` configured to non-default value don't look
-    * at the old name
+    * naming we need to:
+    *   - if `forceBlankLineBeforeDocstring` (new name) has default value
+    *     (true), fallback to `blankLineBeforeDocstring` (old config) which may
+    *     be configured in .scalafmt.conf
+    *   - if `forceBlankLineBeforeDocstring` configured to non-default value,
+    *     don't look at the old name
     */
   lazy val forceNewlineBeforeDocstringSummary: Boolean =
     forceBlankLineBeforeDocstring && !blankLineBeforeDocstring

scalafmt-core/shared/src/main/scala/org/scalafmt/config/ScalafmtConfig.scala

@@ -30,32 +30,48 @@ import org.scalafmt.util.ValidationOps
   * @param danglingParentheses
   *   If true AND @binPackArguments is true AND @configStyleArguments is false,
   *   then this
-  *
-  * function( longerArg1, longerArg3)
-  *
+  * {{{
+  *     function(
+  *         longerArg1,
+  *         longerArg3)
+  * }}}
   * is formatted like this
-  *
-  * function( longerArg1, longerArg3 )
+  * {{{
+  *     function(
+  *         longerArg1,
+  *         longerArg3
+  *     )
+  * }}}
   * @param rewriteTokens
   *   Map of tokens to rewrite. For example, Map("⇒" -> "=>") will rewrite
   *   unicode arrows to regular ascii arrows.
   * @param importSelectors
   *   Controls formatting of import selectors with multiple names from the same
-  *   package; If [[org.scalafmt.config.ImportSelectors.binPack]], import
-  *   selectors are arranged to fit within the maximum line width If
-  *   [[org.scalafmt.config.ImportSelectors.noBinPack]], import selectors are
-  *   broken to one per line If
-  *   [[org.scalafmt.config.ImportSelectors.singleLine]], import selectors are
-  *   kept on a single line The default setting is currently `noBinPack`.
+  *   package
+  *   - If [[org.scalafmt.config.ImportSelectors.binPack]], import selectors are
+  *     arranged to fit within the maximum line width
+  *   - If [[org.scalafmt.config.ImportSelectors.noBinPack]], import selectors
+  *     are broken to one per line
+  *   - If [[org.scalafmt.config.ImportSelectors.singleLine]], import selectors
+  *     are kept on a single line The default setting is currently `noBinPack`.
   * @param indentYieldKeyword
-  *   If true, indents `yield` by two spaces for (i <- j) yield banana If false,
-  *   treats `yield` like `else` for (i <- j) yield banana
+  *   - If true, indents `yield` by two spaces
+  * {{{
+  *       for (i <- j)
+  *         yield banana
+  * }}}
+  *   - If false, treats `yield` like `else`
+  * {{{
+  *       for (i <- j)
+  *       yield banana
+  * }}}
   * @param lineEndings
-  *   If [[LineEndings.unix]], output will include only unix line endings If
-  *   [[LineEndings.windows]], output will include only windows line endings If
-  *   [[LineEndings.preserve]], output will include endings included in original
-  *   file (windows if there was at least one windows line ending, unix if there
-  *   was zero occurrences of windows line endings)
+  *   - If [[LineEndings.unix]], output will include only unix line endings
+  *   - If [[LineEndings.windows]], output will include only windows line
+  *     endings
+  *   - If [[LineEndings.preserve]], output will include endings included in
+  *     original file (windows if there was at least one windows line ending,
+  *     unix if there was zero occurrences of windows line endings)
   * @param includeCurlyBraceInSelectChains
   *   NB: failure unless newlines.source=classic If true, includes curly brace
   *   applications in select chains/pipelines.

scalafmt-core/shared/src/main/scala/org/scalafmt/config/ScalafmtOptimizer.scala

@@ -24,17 +24,23 @@ import metaconfig._
   *   Do not optimize inside certain areas such as term apply.
   * @param pruneSlowStates
   *   Eliminate solutions that move slower than other solutions.
+  *   - If a solution reaches a point X first and other solution that reaches
+  *     the same point later, the first solution is preferred if it can be
+  *     verified to be always better (see
+  *     [[org.scalafmt.internal.State.alwaysBetter]]).
+  *   - Note. This affects the output positively because it breaks a tie between
+  *     two equally expensive solutions by eliminating the slower one.
   *
-  * If a solution reaches a point X first and other solution that reaches the
-  * same point later, the first solution is preferred if it can be verified to
-  * be always better (see [[org.scalafmt.internal.State.alwaysBetter]]).
-  *
-  * Note. This affects the output positively because it breaks a tie between two
-  * equally expensive solutions by eliminating the slower one.
-  *
-  * Example, solution 1 is preferred even though both solutions cost the same:
-  *
-  * // solution 1 a + b + c + d // solution 2 a + b + c + d
+  *   - Example: solution 1 is preferred even though both solutions cost the
+  *     same:
+  * {{{
+  *       // solution 1
+  *       a + b +
+  *       c + d
+  *       // solution 2
+  *       a +
+  *       b + c + d
+  * }}}
   * @param recurseOnBlocks
   *   Recursively format { ... } blocks inside no optimization zones.
   *

scalafmt-core/shared/src/main/scala/org/scalafmt/config/Spaces.scala

@@ -9,24 +9,40 @@ import metaconfig._
   * @param afterTripleEquals
   *   If true, formats ===( as === (
   * @param inImportCurlyBraces
-  *   If true, formats `import a.b.{ c, d }`. If false, formats `import a.b.{c,
-  *   d}`.
+  *   - If true, formats
+  * {{{
+  *     import a.b.{ c, d}
+  * }}}
+  *   - If false, formats
+  * {{{
+  *     import a.b.{c, d}
+  * }}}
   * @param inInterpolatedStringCurlyBraces
-  *   If true, formats `s"\${var1} \${var2.sub}"` as `s"\${ var1 } \${ var2.sub
-  *   }"`.
+  *   If true, formats
+  * {{{
+  *     s"\${var1} \${var2.sub}"
+  * }}}
+  * as
+  * {{{
+  *     s"\${ var1 } \${ var2.sub }"
+  * }}}
   * @param inParentheses
   *   If true, formats `foo(a, b)` as `foo( a, b )`.
   * @param neverAroundInfixTypes
-  *   If ["##"] is specified as operator then formats `Generic[Foo] ## Repr` as
-  *   `Generic[Foo]##Repr`.
+  *   If ["##"] is specified as operator then formats {{{Generic[Foo] ## Repr}}}
+  *   as {{{Generic[Foo]##Repr}}}.
   * @param afterKeywordBeforeParen
   *   if false, does not add a space between a keyword and a parenthesis. For
-  *   example: if(a) println("HELLO!") while(a) println("HELLO!")
+  *   example:
+  * {{{
+  *     if(a) println("HELLO!")
+  *     while(a) println("HELLO!")
+  * }}}
   * @param inByNameTypes
-  *   If false, removes space in by-name parameter. `def foo(a: =>A)`
+  *   If false, removes space in by-name parameter: {{{def foo(a: =>A)}}}
   * @param afterSymbolicDefs
-  *   If true, adds a single space after an operator method For example: def <=>
-  *   [T](that: T): Boolean
+  *   If true, adds a single space after an operator method. For example:
+  *   {{{def <=> [T](that: T): Boolean}}}
   */
 case class Spaces(
     beforeContextBoundColon: Spaces.BeforeContextBound =

scalafmt-core/shared/src/main/scala/org/scalafmt/internal/Indent.scala

@@ -36,8 +36,10 @@ object Length {
   /** Indent up to the column of the left token.
     *
     * Example: the opening parenthesis below indents by [[StateColumn]].
-    *
-    * foobar(arg1, arg2)
+    * {{{
+    *   foobar1(arg1,
+    *           arg2)
+    * }}}
     */
   case object StateColumn extends Length {
     override def withStateOffset(offset: Int): Int = offset