Apply suggestions from code review

0101 · gewarren · web-flow · commit 0c1ede77624c · 2024-10-31T12:48:50.000+01:00
Co-authored-by: Genevieve Warren &lt;24882762+gewarren@users.noreply.github.com&gt;
diff --git a/docs/fsharp/whats-new/fsharp-9.md b/docs/fsharp/whats-new/fsharp-9.md
@@ -69,7 +69,7 @@ type Contact =
 type Person = { name: string; contact: Contact }
 ```
 
-Previously, you would have to write something like:
+Previously, you had to write something like:
 
 ```fsharp
 let canSendEmailTo person =
@@ -87,7 +87,7 @@ let canSendEmailTo person =
 
 ### Partial active patterns can return `bool` instead of `unit option`
 
-Previously, partial active patterns would return `Some ()` to indicate a match and `None` otherwise. Now, they can also return `bool`.
+Previously, partial active patterns returned `Some ()` to indicate a match and `None` otherwise. Now, they can also return `bool`.
 
 For example, the active pattern for the following:
 ```fsharp
@@ -96,7 +96,8 @@ match key with
 | CaseInsensitive "bar" -> ...
 ```
 
-Would previously be written as:
+Was previously written as:
+
 ```fsharp
 let (|CaseInsensitive|_|) (pattern: string) (value: string) =
     if String.Equals(value, pattern, StringComparison.OrdinalIgnoreCase) then
@@ -114,7 +115,7 @@ let (|CaseInsensitive|_|) (pattern: string) (value: string) =
 
 ### Prefer extension methods to intrinsic properties when arguments are provided
 
-To align with a pattern seen in some .NET libraries, where extension methods are defined with the same names as intrinsic properties of a type, F# will now resolve these extension methods instead of failing the type check.
+To align with a pattern seen in some .NET libraries, where extension methods are defined with the same names as intrinsic properties of a type, F# now resolves these extension methods instead of failing the type check.
 
 Example:
 
@@ -134,7 +135,7 @@ f.X(1) // We can now call the extension method to set the property and chain fur
 
 ### Support for empty-bodied computation expressions
 
-F# now supports empty [computation expressions](https://learn.microsoft.com/dotnet/fsharp/language-reference/computation-expressions).
+F# now supports empty [computation expressions](../language-reference/computation-expressions.md).
 
 <pre class="language-fsharp"><code>let xs = seq { } // Empty sequence```
 
@@ -208,13 +209,13 @@ All of these will now work:
 #nowarn "FS0057"
 ```
 
-It's probably a good idea to stick to the same style throughout your project.
+It's a good idea to use the same style throughout your project.
 
 ### Warning about TailCall attribute on non-rec functions or let-bound values
 
-F# will now emit a warning when you put the `[<TailCall>]` attribute somewhere it doesn't belong. While it has no effect on what the code does, it could confuse someone reading it.
+F# now emits a warning when you put the `[<TailCall>]` attribute somewhere it doesn't belong. While it has no effect on what the code does, it could confuse someone reading it.
 
-For example, these will now emit a warning:
+For example, these usages will now emit a warning:
 ```fsharp
 [&lt;TailCall&gt;]
 let someNonRecFun x = x + x
@@ -230,15 +231,15 @@ let rec someRecLetBoundValue = nameof(someRecLetBoundValue)
 
 The compiler now correctly enforces the `AttributeTargets` on let values, functions, union case declarations, implicit constructors, structs, and classes. This can prevent some hard-to-notice bugs, such as forgetting to add the unit argument to an Xunit test.
 
-Previously, you could have written:
+Previously, you could write:
 
 ```fsharp
 [&lt;Fact&gt;]
 let ``this test always fails`` =
   Assert.True(false)
 ```
 
-Run the tests with `dotnet test` and they would pass. Since the test function is not actually a function, it is ignored by the test runner.
+When you ran the tests with `dotnet test`, they would pass. Since the test function is not actually a function, it was ignored by the test runner.
 
 Now, with correct attribute enforcement, you will get an `error FS0842: This attribute is not valid for use on this language element`.
 
@@ -248,17 +249,17 @@ Now, with correct attribute enforcement, you will get an `error FS0842: This att
 
 The `List`, `Array`, and `Seq` modules have new functions for random sampling and shuffling. This makes F# easier to use for common data science, machine learning, game development, and other scenarios where randomness is needed.
 
-All functions have variants using:
+All functions have the following variants:
 
-* An implicit thread-safe shared [`Random`](https://learn.microsoft.com/dotnet/api/system.random) instance
-* Taking a `Random` instance as an argument
-* Taking a custom `randomizer` function, which should return a float value greater than or equal to 0.0 and less than 1.0
+* One that uses an implicit, thread-safe, shared <xref:System.Random> instance
+* One that takes a `Random` instance as an argument
+* One that takes a custom `randomizer` function, which should return a float value greater than or equal to 0.0 and less than 1.0
 
-There are four functions (each with three variants) available:
+There are four functions (each with three variants) available: `Shuffle`, `Choice`, `Choices`, and `Sample`.
 
 #### Shuffle
 
-The shuffle functions return a new collection of the same type and size, with each item in a randomly mixed position. The chance to end up in any position is weighted evenly on the length of the collection.
+The `Shuffle` functions return a new collection of the same type and size, with each item in a randomly mixed position. The chance to end up in any position is weighted evenly on the length of the collection.
 
 ```fsharp
 let allPlayers = [ "Alice"; "Bob"; "Charlie"; "Dave" ]
@@ -269,7 +270,7 @@ For arrays, there are also `InPlace` variants that shuffle the array in place.
 
 #### Choice
 
-The choice functions return a single random element from the given collection. The random choice is weighted evenly on the size of the collection.
+The `Choice` functions return a single random element from the given collection. The random choice is weighted evenly on the size of the collection.
 
 ```fsharp
 let allPlayers = [ "Alice"; "Bob"; "Charlie"; "Dave" ]
@@ -278,7 +279,7 @@ let randomPlayer = allPlayers |> List.randomChoice // "Charlie"
 
 #### Choices
 
-Choices select N elements from the input collection in random order, allowing elements to be selected more than once.
+The `Choices` functions select N elements from the input collection in random order, allowing elements to be selected more than once.
 
 ```fsharp
 let weather = [ "Raining"; "Sunny"; "Snowing"; "Windy" ]
@@ -287,7 +288,7 @@ let forecastForNext3Days = weather |> List.randomChoices 3 // [ "Windy"; "Snowin
 
 #### Sample
 
-Sample selects N elements from the input collection in random order, without allowing elements to be selected more than once. N cannot be greater than the collection length.
+The `Sample` functions select N elements from the input collection in random order, without allowing elements to be selected more than once. N cannot be greater than the collection length.
 
 ```fsharp
 let foods = [ "Apple"; "Banana"; "Carrot"; "Donut"; "Egg" ]
@@ -298,11 +299,11 @@ For a full list of functions and their variants, see ([RFC #1135](https://github
 
 ### Parameterless constructor for `CustomOperationAttribute`
 
-This makes it easier to create a custom operation for a computation expression builder. It will use the name of the method instead of having to explicitly name it (when in most cases the name matches the method name already).
+This constructor makes it easier to create a custom operation for a computation expression builder. It uses the name of the method instead of having to explicitly name it (when in most cases the name matches the method name already).
 
 ```fsharp
 type FooBuilder() =
-    [&lt;CustomOperation&gt;]  // Previously would have to be [&lt;CustomOperation("bar")&gt;]
+    [&lt;CustomOperation&gt;]  // Previously had to be [&lt;CustomOperation("bar")&gt;]
     member _.bar(state) = state
 ```
 
@@ -312,21 +313,23 @@ When using F# lists and sets from C#, you can now use collection expressions to
 
 Instead of:
 
-<pre><code class="language-csharp">FSharpSet&lt;int&gt; mySet = SetModule.FromArray([1, 2, 3]);
+```csharp
+FSharpSet&lt;int&gt; mySet = SetModule.FromArray([1, 2, 3]);
 ```
 
 You can now write:
 
-<pre><code class="language-csharp">FSharpSet&lt;int&gt; mySet = [ 1, 2, 3 ];
+```csharp
+FSharpSet&lt;int&gt; mySet = [ 1, 2, 3 ];
 ```
 
-This makes it easier to use the F# immutable collections from C#, for example when you need their structural equality, which `System.Collections.Immutable` collections don't have.
+Collection expressions make it easier to use the F# immutable collections from C#. You might want to use the F# collections when you need their structural equality, which <xref:System.Collections.Immutable> collections don't have.
 
 ## Quality of life improvements
 
 ### Parser recovery
 
-There have been continuous improvements in parser recovery, meaning that tooling (e.g. syntax highlighting) still works with code when you're in the middle of editing it and it may not be syntactically correct at all times.
+There have been continuous improvements in parser recovery, meaning that tooling (for example, syntax highlighting) still works with code when you're in the middle of editing it and it might not be syntactically correct at all times.
 
 For example, the parser will now recover on unfinished `as` patterns, object expressions, enum case declarations, record declarations, complex primary constructor patterns, unresolved long identifiers, empty match clauses, missing union case fields, and missing union case field types.
 
@@ -335,22 +338,24 @@ For example, the parser will now recover on unfinished `as` patterns, object exp
 Diagnostics, or understanding what the compiler doesn't like about your code, are an important part of the user experience with F#. There are a number of new or improved diagnostic messages or more precise diagnostic locations in F# 9.
 
 These include:
+
 - Ambiguous override method in object expression
 - Abstract members when used in non-abstract classes
-- When a property has the same name as a discriminated union case
+- Property that has the same name as a discriminated union case
 - Active pattern argument count mismatch
 - Unions with duplicated fields
 - Using `use!` with `and!` in computation expressions
 
-There is also a new compile-time error for classes with over 65,520 methods in generated [IL](https://learn.microsoft.com/dotnet/standard/managed-code#intermediate-language--execution). Such classes won't be loadable by the CLR and would result in a runtime error. (Not that you would ever really want to have so many methods, but there have been cases with generated code.)
+There is also a new compile-time error for classes with over 65,520 methods in generated [IL](../../standard/managed-code.md#intermediate-language--execution). Such classes aren't loadable by the CLR and would result in a run-time error. (Not that you would ever really want to have so many methods, but there have been cases with generated code.)
 
 ### Real visibility
 
-There is a quirk with how F# generates assemblies that results in private members being written to [IL](https://learn.microsoft.com/dotnet/standard/managed-code#intermediate-language--execution) as internal. This allows inappropriate access to private members from non-F# projects that have access to an F# project via [`InternalsVisibleTo`](https://learn.microsoft.com/dotnet/api/system.runtime.compilerservices.internalsvisibletoattribute).
+There is a quirk with how F# generates assemblies that results in private members being written to [IL](../../standard/managed-code.md#intermediate-language--execution) as internal. This allows inappropriate access to private members from non-F# projects that have access to an F# project via [`InternalsVisibleTo`](xref:System.Runtime.CompilerServices.InternalsVisibleToAttribute).
 
 Now, there is an opt-in fix for this behavior available via the `--realsig+` compiler flag. Try it in your solution to see if any of your projects depend on this behavior. You can add it to your `.fsproj` files like this:
 
-<pre><code class="language-xml">&lt;PropertyGroup&gt;
+```xml
+<PropertyGroup>
     &lt;OtherFlags&gt;--realsig+&lt;/OtherFlags&gt;
 &lt;/PropertyGroup&gt;
 ```
@@ -373,7 +378,8 @@ let ids = Array.init 1000 MyId
 let missingId = MyId -1
 
 // used to box 1000 times, doesn't box anymore
-let _ = ids |> Array.contains missingId```
+let _ = ids |> Array.contains missingId
+```
 
 You can read all the details here: [F# Developer Stories: How we’ve finally fixed a 9-year-old performance issue](https://devblogs.microsoft.com/dotnet/fsharp-developer-stories-how-weve-finally-fixed-a-9yearold-performance-issue/).
 
@@ -388,17 +394,20 @@ The compiler now generates optimized code for more instances of `start..finish`
 This leads to anywhere from 1.25× up to 8× speed up in loops:
 
 ```fsharp
-for … in start..finish do …```
+for … in start..finish do …
+```
 
 List/array expressions:
 
 ```fsharp
-[start..step..finish]```
+[start..step..finish]
+```
 
 and comprehensions:
 
 ```fsharp
-[for n in start..finish -> f n]```
+[for n in start..finish -> f n]
+```
 
 ### Optimized `for x in xs -> …` in list and array comprehensions
 
@@ -417,16 +426,17 @@ Sometimes extra parentheses are used for clarity, but sometimes they are just no
 For example:
 ```fsharp
 let f (x) = x // -> let f x = x
-let _ = (2 * 2) + 3 // -> let _ = 2 * 2 + 3```
+let _ = (2 * 2) + 3 // -> let _ = 2 * 2 + 3
+```
 
-### Custom Visualizer support for F# in Visual Studio
+### Custom visualizer support for F# in Visual Studio
 
 The debugger visualizer in Visual Studio now works with F# projects.
 
 ![debug visualizer](../media/whats-new/fsharp-9/vs-visualizer.gif)
 
 ### Signature tooltips shown mid-pipeline
 
-Previously, no signature help was offered in a situation like the following, where a function in the middle of a pipeline already had a complex curried parameter (e.g., a lambda) applied to it. Now, the signature tooltip will show up for the next parameter (`state`):
+Previously, no signature help was offered in a situation like the following, where a function in the middle of a pipeline already had a complex curried parameter (for example, a lambda) applied to it. Now, the signature tooltip shows up for the next parameter (`state`):
 
 ![tooltip](../media/whats-new/fsharp-9/help.png)
