Merge branch 'main' into patch-3

Author: atsansone

examples/language/test/records_test.dart

@@ -115,7 +115,7 @@ void main() {
   test('record-multiple-returns', () {
     // #docregion record-multiple-returns
     // Returns multiple values in a record:
-    (String, int) userInfo(Map<String, dynamic> json) {
+    (String name, int age) userInfo(Map<String, dynamic> json) {
       return (json['name'] as String, json['age'] as int);
     }
 
@@ -125,7 +125,7 @@ void main() {
       'color': 'blue',
     };
 
-    // Destructures using a record pattern:
+    // Destructures using a record pattern with positional fields:
     var (name, age) = userInfo(json);
 
     /* Equivalent to:
@@ -137,4 +137,25 @@ void main() {
     name;
     age;
   });
+
+  test('record-name-destructure', () {
+    // #docregion record-name-destructure
+    ({String name, int age}) userInfo(Map<String, dynamic> json)
+    // #enddocregion record-name-destructure
+    {
+      return (name: json['name'] as String, age: json['age'] as int);
+    }
+
+    final json = <String, dynamic>{
+      'name': 'Dash',
+      'age': 10,
+      'color': 'blue',
+    };
+    // #docregion record-name-destructure
+    // Destructures using a record pattern with named fields:
+    final (:name, :age) = userInfo(json);
+    // #enddocregion record-name-destructure
+    name;
+    age;
+  });
 }

src/content/language/concurrency.md

@@ -280,7 +280,7 @@ complete. A well-behaved app starts quickly, getting to the event loop as soon
 as possible. The app then responds to each queued event promptly, using
 asynchronous operations as necessary.
 
-[async-await]: {{site.url}}/codelabs/async-await
+[async-await]: /codelabs/async-await
 
 ### The isolate life cycle
 

src/content/language/extension-types.md

@@ -446,8 +446,9 @@ It's important to be aware of this quality when using extension types.
 Always keep in mind that an extension type exists and matters at compile time,
 but gets erased _during_ compilation.
 
-An expression with the extension type `E` and the representation type `R`
-as its static type will be an object with type `R` at run time.
+For example, consider an expression `e` whose static type is the
+extension type `E`, and the representation type of `E` is `R`.
+Then, the run-time type of the value of `e` is a subtype of `R`.
 Even the type itself is erased;
 `List<E>` is exactly the same thing as `List<R>` at run time.
 

src/content/language/patterns.md

@@ -279,8 +279,8 @@ in a map. This section describes even more use cases, answering:
 
 ### Destructuring multiple returns
 
-[Records][] allow aggregating and returning multiple values from a single function
-call. Patterns add the ability to destructure a record's fields
+Records allow aggregating and [returning multiple values][] from a single
+function call. Patterns add the ability to destructure a record's fields
 directly into local variables, inline with the function call.
 
 Instead of individually declaring new local variables for each record field,
@@ -295,7 +295,8 @@ var age = info.$2;
 
 You can destructure the fields of a record that a function returns into local
 variables using a [variable declaration](#variable-declaration) or
-[assigment pattern](#variable-assignment), and a record pattern as its subpattern:
+[assigment pattern](#variable-assignment), and a [record pattern][record]
+as its subpattern:
 
 <?code-excerpt "language/lib/patterns/destructuring.dart (destructure-multiple-returns-2)"?>
 ```dart
@@ -424,7 +425,7 @@ This case pattern simultaneously validates that:
 [collection literals]: /language/collections#control-flow-operators
 [null-assert pattern]: /language/pattern-types#null-assert
 [record]: /language/pattern-types#record
-[Records]: /language/records
+[returning multiple values]: /language/records#multiple-returns
 [refutable]: /resources/glossary#refutable-pattern
 [constant]: /language/pattern-types#constant
 [list]: /language/pattern-types#list

src/content/language/records.md

@@ -176,12 +176,12 @@ of their fields.
 
 Records allow functions to return multiple values bundled together.
 To retrieve record values from a return,
-destructure the values into local variables using [pattern matching][pattern].
+[destructure][] the values into local variables using [pattern matching][pattern].
 
 <?code-excerpt "language/test/records_test.dart (record-multiple-returns)"?>
 ```dart
 // Returns multiple values in a record:
-(String, int) userInfo(Map<String, dynamic> json) {
+(String name, int age) userInfo(Map<String, dynamic> json) {
   return (json['name'] as String, json['age'] as int);
 }
 
@@ -191,7 +191,7 @@ final json = <String, dynamic>{
   'color': 'blue',
 };
 
-// Destructures using a record pattern:
+// Destructures using a record pattern with positional fields:
 var (name, age) = userInfo(json);
 
 /* Equivalent to:
@@ -201,6 +201,18 @@ var (name, age) = userInfo(json);
 */
 ```
 
+You can also destructure a record using its [named fields](#record-fields),
+using the colon `:` syntax, which you can read more about on the
+[Pattern types][] page:
+
+<?code-excerpt "language/test/records_test.dart (record-name-destructure)"?>
+```dart
+({String name, int age}) userInfo(Map<String, dynamic> json)
+// ···
+// Destructures using a record pattern with named fields:
+final (:name, :age) = userInfo(json);
+```
+
 You can return multiple values from a function without records,
 but other methods come with downsides.
 For example, creating a class is much more verbose, and using other collection
@@ -217,3 +229,5 @@ parallelization of futures of different types, which you can read about in the
 [pattern]: /language/patterns#destructuring-multiple-returns
 [`dart:async` documentation]: /libraries/dart-async#handling-errors-for-multiple-futures
 [parameters and arguments]: /language/functions#parameters
+[destructure]: /language/patterns#destructuring
+[Pattern types]: /language/pattern-types#record

src/content/tutorials/server/fetch-data.md

@@ -244,7 +244,7 @@ void main() async {
 
 This results in the following JSON-formatted output,
 which can also be seen in your browser at
-[{{site.url}}/f/packages/http.json][mock-http-json].
+[`/f/packages/http.json`][mock-http-json].
 
 ```json
 {