Continue docregion/excerpt cleanup (#5703)

- Migrates away from last unnamed regions
- Close some unclosed regions
- Some other misc cleanup

Contributes to #5593

Author: parlough

examples/async_await/bin/futures_intro.dart

@@ -19,4 +19,4 @@ void main() {
   fetchUserOrder();
   print('Fetching user order...');
 }
-// #enddocregion no-error
+// #enddocregion no-error, error

examples/extension_methods/lib/string_extensions/usage_simple_extension.dart

@@ -11,11 +11,11 @@ void main() {
   print(double.parse('42'));
 
   // WITH extension methods.
-  // #docregion import-and-use
+// #docregion import-and-use
   print('42'.padLeft(5)); // Use a String method.
-  // #docregion basic
+// #docregion basic
   print('42'.parseInt()); // Use an extension method.
-  // #enddocregion basic, import-and-use
+// #enddocregion basic, import-and-use
   print('42'.parseDouble());
 
   // var vs. dynamic.

examples/misc/lib/language_tour/classes/employee.dart

@@ -22,7 +22,7 @@ class Employee extends Person {
   Employee.fromJson(super.data) : super.fromJson() {
     print('in Employee');
   }
-// #docregion method-then-constructor
+  // #docregion method-then-constructor
 }
 // #enddocregion method-then-constructor
 

examples/misc/lib/language_tour/classes/extends.dart

@@ -26,3 +26,4 @@ class SmartTelevision extends Television {
   void _upgradeApps() {}
   // #docregion smart-tv
 }
+// #enddocregion smart-tv

examples/misc/lib/library_tour/core/hash_code.dart

@@ -1,5 +1,4 @@
 // ignore_for_file: unrelated_type_equality_checks
-// #docregion
 class Person {
   final String firstName, lastName;
 

examples/misc/lib/library_tour/core/iterator.dart

@@ -2,26 +2,26 @@ import 'dart:collection';
 
 final Iterator<Process> _it = [Process(), Process(), Process()].iterator;
 
-// #docregion
+// #docregion structure
 class Process {
   // Represents a process...
-  // #enddocregion
+  // #enddocregion structure
   static int _nextId = 0;
   final int id = _nextId++;
-  // #docregion
+  // #docregion structure
 }
 
 class ProcessIterator implements Iterator<Process> {
   @override
   Process get current => /*...*/
-      // #enddocregion
+      // #enddocregion structure
       _it.current;
-  // #docregion
+  // #docregion structure
   @override
   bool moveNext() => /*...*/
-      // #enddocregion
+      // #enddocregion structure
       _it.moveNext();
-  // #docregion
+  // #docregion structure
 }
 
 // A mythical class that lets you iterate through all
@@ -35,8 +35,9 @@ void main() {
   // Iterable objects can be used with for-in.
   for (final process in Processes()) {
     // Do something with the process.
-    // #enddocregion
+    // #enddocregion structure
     print(process.id);
-    // #docregion
+    // #docregion structure
   }
 }
+// #enddocregion structure

examples/misc/lib/library_tour/io/http_server.dart

@@ -1,13 +1,13 @@
 import 'dart:io';
 
 int stopAfter = 10;
-// #docregion
+// #docregion process-requests
 Future<void> main() async {
   final requests = await HttpServer.bind('localhost', 8888);
-  // #enddocregion
+  // #enddocregion process-requests
   // ignore: no_leading_underscores_for_local_identifiers
   final _requests = requests.take(stopAfter);
-  // #docregion
+  // #docregion process-requests
   await for (final request in _requests) {
     processRequest(request);
   }
@@ -28,3 +28,4 @@ void processRequest(HttpRequest request) {
   }
   response.close();
 }
+// #enddocregion process-requests

examples/non_promotion/lib/non_promotion.dart

@@ -84,10 +84,10 @@ void miscDeclAnalyzedButNotTested() {
 
   {
     void f(int? i, int? j) {
-      // #docregion catch-null-check
-      // #enddocregion catch-null-check
       if (i == null) return;
+      // #docregion catch-null-check
       try {
+        // #enddocregion catch-null-check
         i = j; // (1)
         // ... Additional code ...
         if (i == null) return; // (2)
@@ -106,10 +106,10 @@ void miscDeclAnalyzedButNotTested() {
 
   {
     void f(int? i, int? j) {
-      // #docregion catch-bang
-      // #enddocregion catch-bang
       if (i == null) return;
+      // #docregion catch-bang
       try {
+        // #enddocregion catch-bang
         i = j; // (1)
         // ... Additional code ...
         if (i == null) return; // (2)

src/content/libraries/dart-core.md

@@ -953,7 +953,7 @@ If you create a class that can provide Iterators for use in for-in loops,
 extend (if possible) or implement Iterable.
 Implement Iterator to define the actual iteration ability.
 
-<?code-excerpt "misc/lib/library_tour/core/iterator.dart"?>
+<?code-excerpt "misc/lib/library_tour/core/iterator.dart (structure)"?>
 ```dart
 class Process {
   // Represents a process...
@@ -990,13 +990,11 @@ catch. Errors are conditions that you don't expect or plan for.
 A couple of the most common errors are:
 
 [NoSuchMethodError][]
-
-:   Thrown when a receiving object (which might be null) does not
-    implement a method.
+: Thrown when a receiving object (which might be `null`) does not
+  implement a method.
 
 [ArgumentError][]
-
-:   Can be thrown by a method that encounters an unexpected argument.
+: Can be thrown by a method that encounters an unexpected argument.
 
 Throwing an application-specific exception is a common way to indicate
 that an error has occurred. You can define a custom exception by

src/content/libraries/dart-io.md

@@ -217,7 +217,7 @@ This server listens on port 8888 and address 127.0.0.1 (localhost),
 responding to requests for the path `/dart`. For any other path,
 the response is status code 404 (page not found).
 
-<?code-excerpt "misc/lib/library_tour/io/http_server.dart" replace="/Future<\w+\W/void/g; /\b_//g"?>
+<?code-excerpt "misc/lib/library_tour/io/http_server.dart (process-requests)" replace="/Future<\w+\W/void/g; /\b_//g"?>
 ```dart
 void main() async {
   final requests = await HttpServer.bind('localhost', 8888);

src/content/tools/non-promotion-reasons.md

@@ -871,7 +871,8 @@ The safest solution is to add a null check inside the `catch` block:
 
 <?code-excerpt "non_promotion/lib/non_promotion.dart (catch-null-check)" replace="/if.*/[!$&!]/g;/(} else {|  \/\/ H.*)/[!$&!]/g;/  }/  [!}!]/g"?>
 ```dart tag=good
-// ···
+try {
+  // ···
 } catch (e) {
   [!if (i != null) {!]
     print(i.isEven); // (3) OK due to the null check in the line above.
@@ -886,7 +887,8 @@ just use the `!` operator:
 
 <?code-excerpt "non_promotion/lib/non_promotion.dart (catch-bang)" replace="/i!/i[!!!]/g"?>
 ```dart
-// ···
+try {
+  // ···
 } catch (e) {
   print(i[!!!].isEven); // (3) OK because of the `!`.
 }