Merge pull request #26727 from dsyme/f6

F# 6 doc revamp

Author: dsyme

.openpublishing.redirection.json

@@ -12967,13 +12967,26 @@
             "source_path": "docs/fsharp/async.md",
             "redirect_url": "/dotnet/fsharp/tutorials/asynchronous-and-concurrent-programming/async"
         },
+        {
+            "source_path": "docs/fsharp/language-reference/asynchronous-workflows.md",
+            "redirect_url": "/dotnet/fsharp/docs/fsharp/language-reference/async-expressions"
+        },
         {
             "source_path": "docs/fsharp/getting-started-netcore.md",
             "redirect_url": "/dotnet/fsharp/get-started/get-started-command-line"
         },
         {
             "source_path": "docs/fsharp/introduction-to-functional-programming/functions-as-first-class-values.md",
-            "redirect_url": "/dotnet/fsharp/introduction-to-functional-programming/first-class-functions",
+            "redirect_url": "/dotnet/fsharp/tutorials/using-functions",
+            "redirect_document_id": true
+        },
+        {
+            "source_path": "docs/fsharp/introduction-to-functional-programming/first-class-functions.md",
+            "redirect_url": "/dotnet/fsharp/tutorials/using-functions"
+        },
+        {
+            "source_path": "docs/fsharp/introduction-to-functional-programming/index.md",
+            "redirect_url": "/dotnet/fsharp/tutorials/functional-programming-concepts",
             "redirect_document_id": true
         },
         {
@@ -12996,7 +13009,12 @@
         },
         {
             "source_path": "docs/fsharp/tutorials/asynchronous-and-concurrent-programming/index.md",
-            "redirect_url": "/dotnet/fsharp/tutorials/asynchronous-and-concurrent-programming/async"
+            "redirect_url": "/dotnet/fsharp/tutorials/async"
+        },
+        {
+            "source_path": "docs/fsharp/tutorials/asynchronous-and-concurrent-programming/async.md",
+            "redirect_url": "/dotnet/fsharp/tutorials/async",
+            "redirect_document_id": true
         },
         {
             "source_path": "docs/fsharp/tutorials/getting-started/getting-started-command-line.md",

docs/fsharp/get-started/get-started-command-line.md

@@ -1,7 +1,7 @@
 ---
 title: Get started with F# with command-line tools
 description: Learn how to build a simple multi-project solution on F# using the .NET CLI on any operating system (Windows, macOS, or Linux).
-ms.date: 08/15/2020
+ms.date: 10/29/2021
 ---
 # Get started with F# with the .NET CLI
 
@@ -15,22 +15,22 @@ This article assumes that you know how to use a command line and have a preferre
 
 ## Build a simple multi-project solution
 
-Open a command prompt/terminal and use the [dotnet new](../../core/tools/dotnet-new.md) command to create new solution file called `FSNetCore`:
+Open a command prompt/terminal and use the [dotnet new](../../core/tools/dotnet-new.md) command to create new solution file called `FSharpSample`:
 
 ```dotnetcli
-dotnet new sln -o FSNetCore
+dotnet new sln -o FSharpSample
 ```
 
 The following directory structure is produced after running the previous command:
 
 ```console
-FSNetCore
-    ├── FSNetCore.sln
+FSharpSample
+    ├── FSharpSample.sln
 ```
 
 ### Write a class library
 
-Change directories to *FSNetCore*.
+Change directories to *FSharpSample*.
 
 Use the `dotnet new` command, create a class library project in the **src** folder named Library.
 
@@ -41,8 +41,8 @@ dotnet new classlib -lang "F#" -o src/Library
 The following directory structure is produced after running the previous command:
 
 ```console
-└── FSNetCore
-    ├── FSNetCore.sln
+└── FSharpSample
+    ├── FSharpSample.sln
     └── src
         └── Library
             ├── Library.fs
@@ -54,20 +54,14 @@ Replace the contents of `Library.fs` with the following code:
 ```fsharp
 module Library
 
-open Newtonsoft.Json
+open System.Text.Json
 
-let getJsonNetJson value =
-    let json = JsonConvert.SerializeObject(value)
-    $"I used to be {value} but now I'm {json} thanks to Json.NET!"
+let getJson value =
+    let json = JsonSerializer.Serialize(value)
+    value, json
 ```
 
-Add the Newtonsoft.Json NuGet package to the Library project.
-
-```dotnetcli
-dotnet add src/Library/Library.fsproj package Newtonsoft.Json
-```
-
-Add the `Library` project to the `FSNetCore` solution using the [dotnet sln add](../../core/tools/dotnet-sln.md) command:
+Add the `Library` project to the `FSharpSample` solution using the [dotnet sln add](../../core/tools/dotnet-sln.md) command:
 
 ```dotnetcli
 dotnet sln add src/Library/Library.fsproj
@@ -86,8 +80,8 @@ dotnet new console -lang "F#" -o src/App
 The following directory structure is produced after running the previous command:
 
 ```console
-└── FSNetCore
-    ├── FSNetCore.sln
+└── FSharpSample
+    ├── FSharpSample.sln
     └── src
         ├── App
         │   ├── App.fsproj
@@ -104,12 +98,12 @@ open System
 open Library
 
 [<EntryPoint>]
-let main argv =
-    printfn "Nice command-line arguments! Here's what Json.NET has to say about them:"
+let main args =
+    printfn "Nice command-line arguments! Here's what System.Text.Json has to say about them:"
 
-    for arg in argv do
-        let value = getJsonNetJson arg
-        printfn $"{value}"
+    let value, json = getJson {| args=args; year=System.DateTime.Now.Year |}
+    printfn $"Input: %0A{value}"
+    printfn $"Output: %s{json}"
 
     0 // return an integer exit code
 ```
@@ -120,7 +114,7 @@ Add a reference to the `Library` project using [dotnet add reference](../../core
 dotnet add src/App/App.fsproj reference src/Library/Library.fsproj
 ```
 
-Add the `App` project to the `FSNetCore` solution using the `dotnet sln add` command:
+Add the `App` project to the `FSharpSample` solution using the `dotnet sln add` command:
 
 ```dotnetcli
 dotnet sln add src/App/App.fsproj
@@ -138,10 +132,9 @@ dotnet run Hello World
 You should see the following results:
 
 ```console
-Nice command-line arguments! Here's what Json.NET has to say about them:
-
-I used to be Hello but now I'm ""Hello"" thanks to Json.NET!
-I used to be World but now I'm ""World"" thanks to Json.NET!
+Nice command-line arguments! Here's what System.Text.Json has to say about them:
+Input: { args = [|"Hello"; "World"|] year = 2021 }
+Output: {"args":["Hello","World"],"year":2021}
 ```
 
 ## Next steps

docs/fsharp/get-started/get-started-visual-studio.md

@@ -1,12 +1,12 @@
 ---
 title: Get started with F# in Visual Studio
 description: Learn how to use F# with Visual Studio.
-ms.date: 12/20/2019
+ms.date: 10/29/2021
 recommendations: false
 ---
 # Get started with F# in Visual Studio
 
-F# and the Visual F# tooling are supported in the Visual Studio integrated development environment (IDE).
+F# is supported in the Visual Studio integrated development environment (IDE).
 
 To begin, ensure that you have [Visual Studio installed with F# support](install-fsharp.md#install-f-with-visual-studio).
 
@@ -35,10 +35,10 @@ Let's get started by writing some code. Make sure that the `Program.fs` file is
 The previous code sample defines a function called `square` that takes an input named `x` and multiplies it by itself. Because F# uses [Type inference](../language-reference/type-inference.md), the type of `x` doesn't need to be specified. The F# compiler understands the types where multiplication is valid and assigns a type to `x` based on how `square` is called. If you hover over `square`, you should see the following:
 
 ```fsharp
-val square: x:int -> int
+val square: x: int -> int
 ```
 
-This is what is known as the function's type signature. It can be read like this: "Square is a function that takes an integer named x and produces an integer". The compiler gave `square` the `int` type for now; this is because multiplication is not generic across *all* types but rather a closed set of types. The F# compiler will adjust the type signature if you call `square` with a different input type, such as a `float`.
+This is what is known as the function's type signature. It can be read like this: "Square is a function that takes an integer named x and produces an integer". The compiler gave `square` the `int` type for now.
 
 Another function, `main`, is defined, which is decorated with the `EntryPoint` attribute. This attribute tells the F# compiler that program execution should start there. It follows the same convention as other [C-style programming languages](https://en.wikipedia.org/wiki/Entry_point#C_and_C.2B.2B), where command-line arguments can be passed to this function, and an integer code is returned (typically `0`).
 

docs/fsharp/get-started/get-started-vscode.md

@@ -1,7 +1,7 @@
 ---
 title: Get Started with F# in Visual Studio Code
 description: Learn how to use F# with Visual Studio Code and the Ionide plugin suite.
-ms.date: 07/23/2021
+ms.date: 10/29/2021
 ---
 # Get Started with F# in Visual Studio Code
 
@@ -55,7 +55,7 @@ toPigLatin "banana";;
 You should see the following result:
 
 ```fsharp
-val it : string = "ananabay"
+val it: string = "ananabay"
 ```
 
 Now, let's try with a vowel as the first letter. Enter the following:
@@ -67,7 +67,7 @@ toPigLatin "apple";;
 You should see the following result:
 
 ```fsharp
-val it : string = "appleyay"
+val it: string = "appleyay"
 ```
 
 The function appears to be working as expected. Congratulations, you just wrote your first F# function in Visual Studio Code and evaluated it with FSI!
@@ -86,7 +86,7 @@ If the first character in a word starts with a vowel, add "yay" to the end of th
 You may have noticed the following in FSI:
 
 ```fsharp
-val toPigLatin : word:string -> string
+val toPigLatin: word: string -> string
 ```
 
 This states that `toPigLatin` is a function that takes in a `string` as input (called `word`), and returns another `string`. This is known as the [type signature of the function](https://fsharpforfunandprofit.com/posts/function-signatures/), a fundamental piece of F# that's key to understanding F# code. You'll also notice this if you hover over the function in Visual Studio Code.
@@ -125,10 +125,10 @@ Now, in the `main` function, call your Pig Latin generator function on the argum
 
 ```fsharp
 [<EntryPoint>]
-let main argv =
-    for name in argv do
-        let newName = PigLatin.toPigLatin name
-        printfn "%s in Pig Latin is: %s" name newName
+let main args =
+    for arg in args do
+        let newArg = PigLatin.toPigLatin arg
+        printfn "%s in Pig Latin is: %s" arg newArg
 
     0
 ```

docs/fsharp/get-started/get-started-with-visual-studio-for-mac.md

@@ -1,11 +1,11 @@
 ---
 title: Get started with F# in Visual Studio for Mac
 description: Learn how to use F# with Visual Studio for Mac.
-ms.date: 07/03/2018
+ms.date: 10/29/2021
 ---
 # Get started with F# in Visual Studio for Mac
 
-F# and the Visual F# tooling are supported in the Visual Studio for Mac IDE. Ensure that you have [Visual Studio for Mac installed](install-fsharp.md#install-f-with-visual-studio-for-mac).
+F# is supported in the Visual Studio for Mac IDE. Ensure that you have [Visual Studio for Mac installed](install-fsharp.md#install-f-with-visual-studio-for-mac).
 
 ## Creating a console application
 
@@ -53,14 +53,14 @@ Congratulations!  You've created your first F# project in Visual Studio for Mac,
 
 ## Using F# Interactive
 
-One of the best features of the Visual F# tooling in Visual Studio for Mac is the F# Interactive Window.  It allows you to send code over to a process where you can call that code and see the result interactively.
+One of the best features of F# tooling in Visual Studio for Mac is the F# Interactive Window.  It allows you to send code over to a process where you can call that code and see the result interactively.
 
 To begin using it, highlight the `square` function defined in your code.  Next, click on **Edit** from the top level menu.  Next select **Send selection to F# Interactive**.  This executes the code in the F# Interactive Window.  Alternatively, you can right click on the selection and choose **Send selection to F# Interactive**.  You should see the F# Interactive Window appear with the following in it:
 
 ```console
 >
 
-val square : x:int -> int
+val square: x: int -> int
 
 >
 ```
@@ -69,34 +69,34 @@ This shows the same function signature for the `square` function, which you saw
 
 ```console
 > square 12;;
-val it : int = 144
->square 13;;
-val it : int = 169
+val it: int = 144
+> square 13;;
+val it: int = 169
 ```
 
 This executes the function, binds the result to a new name `it`, and displays the type and value of `it`.  Note that you must terminate each line with `;;`.  This is how F# Interactive knows when your function call is finished.  You can also define new functions in F# Interactive:
 
 ```console
 > let isOdd x = x % 2 <> 0;;
 
-val isOdd : x:int -> bool
+val isOdd: x: int -> bool
 
 > isOdd 12;;
-val it : bool = false
+val it: bool = false
 ```
 
 The above defines a new function, `isOdd`, which takes an `int` and checks to see if it's odd!  You can call this function to see what it returns with different inputs.  You can call functions within function calls:
 
 ```console
 > isOdd (square 15);;
-val it : bool = true
+val it: bool = true
 ```
 
 You can also use the [pipe-forward operator](../language-reference/symbol-and-operator-reference/index.md) to pipeline the value into the two functions:
 
 ```console
 > 15 |> square |> isOdd;;
-val it : bool = true
+val it: bool = true
 ```
 
 The pipe-forward operator, and more, are covered in later tutorials.

docs/fsharp/get-started/index.md

@@ -1,7 +1,7 @@
 ---
 title: Get started with F#
 description: Find out how to get started with the F# programming language.
-ms.date: 09/12/2020
+ms.date: 10/29/2021
 ---
 # Get Started with F\#
 

docs/fsharp/get-started/install-fsharp.md

@@ -1,7 +1,7 @@
 ---
 title: Install F#
 description: Learn how to install F# in various different ways.
-ms.date: 12/20/2019
+ms.date: 10/29/2021
 ---
 # Install F\#
 

docs/fsharp/index.yml

@@ -9,7 +9,7 @@ metadata:
   ms.topic: landing-page # Required
   author: cartermp
   ms.author: phcart
-  ms.date: 07/28/2021
+  ms.date: 10/29/2021
 
 landingContent:
   - title: "Learn to program in F#"
@@ -53,12 +53,12 @@ landingContent:
             url: style-guide/conventions.md
       - linkListType: tutorial
         links:
-          - text: "Introduction to Functional Programming in F#"
-            url: introduction-to-functional-programming/index.md
-          - text: "First-class functions"
-            url: introduction-to-functional-programming/first-class-functions.md
+          - text: "Functional programming concepts in F#"
+            url: tutorials/functional-programming-concepts.md
+          - text: "Using Functions in F#"
+            url: tutorials/using-functions.md
           - text: "Async programming in F#"
-            url: tutorials/asynchronous-and-concurrent-programming/async.md
+            url: tutorials/async.md
           - text: "Type providers"
             url: tutorials/type-providers/index.md
 

docs/fsharp/language-reference/active-patterns.md

@@ -132,6 +132,22 @@ Note however that only single-case active patterns can be parameterized.
 
 [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet5008.fs)]
 
+## Struct Representations for Partial Active Patterns
+
+By default, partial active patterns return an `option` value, which will involve an allocation for the `Some` value on a successful match. Alternatively, you can use a [value option](value-options.md) as a return value through the use of the `Struct` attribute:
+
+```fsharp
+open System
+
+[<return: Struct>]
+let (|Int|_|) str =
+   match Int32.TryParse(str) with
+   | (true, n) -> ValueSome n
+   | _ -> ValueNone
+```
+
+The attribute must be specified, because the use of a struct return is not inferred from simply changing the return type to `ValueOption`. For more information, see [RFC FS-1039](https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1039-struct-representation-for-active-patterns.md).
+
 ## See also
 
 - [F# Language Reference](index.md)

docs/fsharp/language-reference/anonymous-records.md

@@ -240,7 +240,7 @@ It is possible to use a .NET API that requires the use of [C# anonymous types](.
 open System.Linq
 
 let names = [ "Ana"; "Felipe"; "Emilia"]
-let nameGrouping = names.Select(fun n -> {| Name = n; FirstLetter = n.[0] |})
+let nameGrouping = names.Select(fun n -> {| Name = n; FirstLetter = n[0] |})
 for ng in nameGrouping do
     printfn $"{ng.Name} has first letter {ng.FirstLetter}"
 ```