Add a bit more structure to own docstrings

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

@@ -12,8 +12,10 @@ import metaconfig.generic.Surface
   *             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
@@ -34,11 +36,14 @@ import metaconfig.generic.Surface
   *   - 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. For example, to align = and <-,
@@ -47,6 +52,7 @@ import metaconfig.generic.Surface
   *     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. For example, to align Defn.Val and
@@ -55,6 +61,7 @@ import metaconfig.generic.Surface
   *     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/IndentOperator.scala

@@ -12,6 +12,7 @@ import metaconfig._
   *   a +=
   *     b
   *   }}}
+  *
   * @param excludeRegex
   *   Regexp for which infix operators should not indent by 2 spaces. For
   *   example, when [[includeRegex]] is `.*` and [[excludeRegex]] is `&&`
@@ -25,6 +26,7 @@ import metaconfig._
   *   a +=
   *     b
   *   }}}
+  *
   * @param exemptScope
   *   If topLevel, allows no indentation on infix operators in top-level
   *   functions only. For example,
@@ -43,6 +45,7 @@ import metaconfig._
   *     b
   *   )
   *   }}}
+  *
   * @see
   *   For context:
   *   [[https://github.com/scala-js/scala-js/blob/master/CODINGSTYLE.md#long-expressions-with-binary-operators]]

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

@@ -10,10 +10,10 @@ import metaconfig._
 import metaconfig.generic.Surface
 
 /** @param penalizeSingleSelectMultiArgList
-  *   If true, adds a penalty to newlines before a dot starting a select chain
-  *   of length one and argument list. The penalty matches the number of
-  *   arguments to the select chain application.
-  *   {{{
+  *   - If true, adds a penalty to newlines before a dot starting a select chain
+  *     of length one and argument list. The penalty matches the number of
+  *     arguments to the select chain application.
+  *     {{{
   *     // If true, favor
   *     logger.elem(a,
   *                 b,
@@ -25,14 +25,16 @@ import metaconfig.generic.Surface
   *     // penalty is proportional to argument count, example:
   *     logger.elem(a, b, c)    // penalty 2
   *     logger.elem(a, b, c, d) // penalty 3, etc.
-  *   }}}
+  *     }}}
+  *   - If false, matches pre-v0.5 behavior. Note. this option may be removed in
+  *     a future release.
   *
-  * If false, matches pre-v0.5 behavior. Note. this option may be removed in a
-  * future release.
   * @param neverBeforeJsNative
   *   If true, a newline will never be placed in front of js.native.
+  *
   * @param sometimesBeforeColonInMethodReturnType
   *   If true, scalafmt may choose to put a newline before colon : at defs.
+  *
   * @param beforeCurlyLambdaParams
   *   - if Never, tries to use a space between the opening curly brace and the
   *     list of parameters of anonymous functions, and some partial functions
@@ -47,6 +49,7 @@ import metaconfig.generic.Surface
   *       consume(n)
   *   }
   *     }}}
+  *
   * @param afterCurlyLambdaParams
   *   - If `never` (default), it will remove any extra lines below curly lambdas
   *     {{{
@@ -74,6 +77,7 @@ import metaconfig.generic.Surface
   *     {{{
   *     xs.map { x => x + 1 }
   *     }}}
+  *
   * @param alwaysBeforeElseAfterCurlyIf
   *   if true, add a new line between the end of a curly if and the following
   *   else. For example
@@ -83,6 +87,7 @@ import metaconfig.generic.Surface
   *   }
   *   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,
@@ -98,6 +103,7 @@ import metaconfig.generic.Surface
   *         .flatMap(f)
   *         .map(g)
   *   }}}
+  *
   * @param avoidAfterYield
   *   If false (legacy behavior), inserts unconditional line break after `yield`
   *   if the yield body doesn't fit on a single line. For example,
@@ -115,28 +121,35 @@ 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
+  *
   * @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
+  *
   * @param afterInfixBreakOnNested
   *   Force breaks around nested (enclosed in parentheses) expressions
+  *
   * @param afterInfixMaxCountPerFile
   *   Switch to `keep` for a given file if the total number of infix operations
   *   in that file exceeds this value
+  *
   * @param afterInfixMaxCountPerExprForSome
   *   Switch to `many` for a given expression (possibly nested) if the number of
   *   operations in that expression exceeds this value AND `afterInfix` had been
   *   set to `some`.
+  *
   * @param topLevelStatementBlankLines
   *   Controls blank line before and/or after a top-level statement.
+  *
   * @param avoidForSimpleOverflow
   *   - punct: don't force break if overflow is only due to trailing punctuation
   *   - tooLong: don't force break if overflow is due to tokens which are too

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

@@ -7,11 +7,11 @@ import metaconfig.generic.Surface
   *   Call-sites where there is a newline after opening ( and newline before
   *   closing ). If true, preserves the newlines and keeps one line per
   *   argument.
+  *
   * @param breaksInsideChains
   *   NB: failure unless newlines.source=classic If true, then the user can opt
   *   out of line breaks inside select chains.
-  *
-  * {{{
+  *   {{{
   *     // original
   *     foo
   *       .map(_ + 1).map(_ + 1)
@@ -25,7 +25,7 @@ import metaconfig.generic.Surface
   *       .map(_ + 1)
   *       .map(_ + 1)
   *       .filter(_ > 2)
-  * }}}
+  *   }}}
   *
   * @param breakChainOnFirstMethodDot
   *   NB: ignored unless newlines.source=classic If true, keeps the line break
@@ -76,6 +76,7 @@ import metaconfig.generic.Surface
   *   See https://github.com/scalameta/scalafmt/issues/938 If true, will force a
   *   line break before a self annotation if there was a line break there
   *   before.
+  *
   * @param forceBlankLineBeforeDocstring
   *   If true, always insert a blank line before docstrings, If false, preserves
   *   blank line only if one exists before. Example:

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

@@ -7,10 +7,9 @@ import metaconfig._
   * @param dequeueOnNewStatements
   *   Clear the search queue on new statements.
   * @param escapeInPathologicalCases
-  *   Use heuristics to escape when the search state grows out of bounds.
-  *
-  * An optimization that trades off optimal formatting output in order to
-  * complete in a reasonable time. Used as a last resort.
+  *   Use heuristics to escape when the search state grows out of bounds. An
+  *   optimization that trades off optimal formatting output in order to
+  *   complete in a reasonable time. Used as a last resort.
   * @param maxVisitsPerToken
   *   Visit the same formatToken at most [[maxVisitsPerToken]] times.
   * @param maxEscapes
@@ -30,7 +29,6 @@ import metaconfig._
   *     [[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:
   *     {{{
@@ -42,10 +40,9 @@ import metaconfig._
   *       b + c + d
   *     }}}
   * @param recurseOnBlocks
-  *   Recursively format { ... } blocks inside no optimization zones.
-  *
-  * By starting a new search queue, we can perform aggressive optimizations
-  * inside optimizations zones.
+  *   Recursively format { ... } blocks inside no optimization zones. By
+  *   starting a new search queue, we can perform aggressive optimizations
+  *   inside optimizations zones.
   * @param forceConfigStyleMinSpan
   *   If negative number, does nothing. If n >= 0, then scalafmt will force
   *   "config style" on Term.Apply nodes IF it has more than