Rename setting to BlankLinesAroundNestedMultilineExpressions and add …

…documentation.

docs/Documentation.md

@@ -93,6 +93,7 @@ fsharp_alternative_long_member_definitions=false
 fsharp_multi_line_lambda_closing_newline=false
 fsharp_disable_elmish_syntax=false
 fsharp_keep_indent_in_branch=false
+fsharp_blank_lines_around_nested_multiline_expressions=true
 fsharp_strict_mode=false
 ```
 
@@ -1060,6 +1061,48 @@ let main argv =
     0
 ```
 
+### fsharp_blank_lines_around_nested_multiline_expressions
+
+Surround **nested** multi-line expressions with blank lines.
+Existing blank lines are always preserved (via trivia).
+Top level expressions will always follow the [2020 blank lines revision](https://github.com/fsprojects/fantomas/blob/master/docs/FormattingConventions.md#2020-revision) principle.
+Default = true.
+
+`defaultConfig`
+
+```fsharp
+let topLevelFunction () =
+    printfn "Something to print"
+
+    try
+            nothing ()
+    with
+    | ex ->
+        splash ()
+    ()
+
+let secondTopLevelFunction () =
+    // ...
+    ()
+```
+
+`{ defaultConfig with BlankLinesAroundNestedMultilineExpressions = false }`
+
+```fsharp
+let topLevelFunction () =
+    printfn "Something to print"
+    try
+            nothing ()
+    with
+    | ex ->
+        splash ()
+    ()
+
+let secondTopLevelFunction () =
+    // ...
+    ()
+```
+
 ### fsharp_strict_mode
 
 If being set, pretty printing is only done via ASTs. Compiler directives, inline comments and block comments will be ignored.

src/Fantomas.Tests/NewlinesAroundInnerMultilineExpressions.fs → src/Fantomas.Tests/BlankLinesAroundNestedMultilineExpressions.fs

@@ -1,12 +1,12 @@
-module Fantomas.Tests.NewlinesAroundInnerMultilineExpressions
+module Fantomas.Tests.BlankLinesAroundNestedMultilineExpressions
 
 open NUnit.Framework
 open FsUnit
 open Fantomas.Tests.TestHelper
 
 let config =
     { config with
-          NewlinesAroundInnerMultilineExpressions = false }
+          BlankLinesAroundNestedMultilineExpressions = false }
 
 [<Test>]
 let ``basic behavior`` () =

src/Fantomas.Tests/Fantomas.Tests.fsproj

@@ -85,7 +85,7 @@
     <Compile Include="DotIndexedSetTests.fs" />
     <Compile Include="MultilineFunctionApplicationsInConditionExpressionsTests.fs" />
     <Compile Include="KeepIndentInBranch.fs" />
-    <Compile Include="NewlinesAroundInnerMultilineExpressions.fs" />
+    <Compile Include="BlankLinesAroundNestedMultilineExpressions.fs" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\Fantomas.Extras\Fantomas.Extras.fsproj" />

src/Fantomas.Tests/KeepIndentInBranch.fs

@@ -883,7 +883,7 @@ module Foo =
         0
 """
         { config with
-              NewlinesAroundInnerMultilineExpressions = false }
+              BlankLinesAroundNestedMultilineExpressions = false }
     |> prepend newline
     |> should
         equal

src/Fantomas/Context.fs

@@ -1508,7 +1508,7 @@ let internal colWithNlnWhenItemIsMultiline (items: ColMultilineItem list) =
     impl items
 
 let internal colWithNlnWhenItemIsMultilineUsingConfig (items: ColMultilineItem list) (ctx: Context) =
-    if ctx.Config.NewlinesAroundInnerMultilineExpressions then
+    if ctx.Config.BlankLinesAroundNestedMultilineExpressions then
         colWithNlnWhenItemIsMultiline items ctx
     else
         col sepNln items (fun (ColMultilineItem (expr, _, _)) -> expr) ctx

src/Fantomas/FormatConfig.fs

@@ -94,7 +94,7 @@ type FormatConfig =
       DisableElmishSyntax: bool
       EndOfLine: EndOfLineStyle
       KeepIndentInBranch: bool
-      NewlinesAroundInnerMultilineExpressions: bool
+      BlankLinesAroundNestedMultilineExpressions: bool
       /// Pretty printing based on ASTs only
       StrictMode: bool }
 
@@ -135,5 +135,5 @@ type FormatConfig =
           DisableElmishSyntax = false
           EndOfLine = EndOfLineStyle.FromEnvironment
           KeepIndentInBranch = false
-          NewlinesAroundInnerMultilineExpressions = true
+          BlankLinesAroundNestedMultilineExpressions = true
           StrictMode = false }