Refactor Constructors page (#5757)

Fixes #2009 
Fixes #2221
Fixes #5227 
Fixes #5506
Fixes #5728
Fixes #5738
Fixes #5739

Author: atsansone

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

@@ -6,8 +6,9 @@
 ///
 // #docregion idiomatic-constructor
 class Point {
-  double x = 0;
-  double y = 0;
+  // Initializer list of variables and values
+  double x = 2.0;
+  double y = 2.0;
 
   // Generative constructor with initializing formal parameters:
   Point(this.x, this.y);
@@ -34,3 +35,66 @@ class Point {
 // #docregion idiomatic-constructor
 }
 // #enddocregion idiomatic-constructor
+
+// #docregion initialize-declaration
+class PointA {
+  double x = 1.0;
+  double y = 2.0;
+
+  // The implicit default constructor sets these variables to (1.0,2.0)
+  // PointA();
+
+  @override
+  String toString() {
+    return 'PointA($x,$y)';
+  }
+}
+// #enddocregion initialize-declaration
+
+// #docregion initialize-formal
+class PointB {
+  final double x;
+  final double y;
+
+  // Sets the x and y instance variables
+  // before the constructor body runs.
+  PointB(this.x, this.y);
+
+  // Initializing formal parameters can also be optional.
+  PointB.optional([this.x = 0.0, this.y = 0.0]);
+}
+// #enddocregion initialize-formal
+
+// #docregion initialize-named
+class PointC {
+  double x; // must be set in constructor
+  double y; // must be set in constructor
+
+  // Generative constructor with initializing formal parameters
+  // with default values
+  PointC.named({this.x = 1.0, this.y = 1.0});
+
+  @override
+  String toString() {
+    return 'PointC.named($x,$y)';
+  }
+}
+
+// Constructor using named variables.
+final pointC = PointC.named(x: 2.0, y: 2.0);
+// #enddocregion initialize-named
+
+// #docregion initialize-null
+class PointD {
+  double? x; // null if not set in constructor
+  double? y; // null if not set in constructor
+
+  // Generative constructor with initializing formal parameters
+  PointD(this.x, this.y);
+
+  @override
+  String toString() {
+    return 'PointD($x,$y)';
+  }
+}
+// #enddocregion initialize-null

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

@@ -0,0 +1,21 @@
+// #docregion named
+class Vector2d {
+// #enddocregion named
+  final double x;
+  final double y;
+
+  Vector2d(this.x, this.y);
+// #docregion named
+  // ...
+  Vector2d.named({required this.x, required this.y});
+}
+
+class Vector3d extends Vector2d {
+  final double z;
+
+  // Forward the y parameter to the named super constructor like:
+  // Vector3d.yzPlane({required double y, required this.z})
+  //       : super.named(x: 0, y: y);
+  Vector3d.yzPlane({required super.y, required this.z}) : super.named(x: 0);
+}
+// #enddocregion named

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

@@ -0,0 +1,16 @@
+// #docregion positional
+class Vector2d {
+  final double x;
+  final double y;
+
+  Vector2d(this.x, this.y);
+}
+
+class Vector3d extends Vector2d {
+  final double z;
+
+  // Forward the x and y parameters to the default super constructor like:
+  // Vector3d(final double x, final double y, this.z) : super(x, y);
+  Vector3d(super.x, super.y, this.z);
+}
+// #enddocregion positional

src/content/guides/whats-new.md

@@ -560,7 +560,7 @@ we made the following changes to this site:
 [Low-level HTML tutorials]: /web/get-started
 
 [native types]: /interop/c-interop#interfacing-with-native-types
-[initializing formal parameters]: /language/constructors#initializing-formal-parameters
+[initializing formal parameters]: /language/constructors#use-initializing-formal-parameters
 [support for packages]: /tools/dartpad#library-support
 [asynchronous programming codelab]: /codelabs/async-await
 [why asynchronous code matters]: /codelabs/async-await#why-asynchronous-code-matters

src/content/language/classes.md

@@ -369,7 +369,7 @@ can pass a static method as a parameter to a constant constructor.
 [`Type`]: {{site.dart-api}}/{{site.sdkInfo.channel}}/dart-core/Type-class.html
 [type test operator]: /language/operators#type-test-operators
 [Getters and setters]: /language/methods#getters-and-setters
-[initializer list]: /language/constructors#initializer-list
+[initializer list]: /language/constructors#use-an-initializer-list
 [factory constructor]: /language/constructors#factory-constructors
 [late-final-ivar]: /effective-dart/design#avoid-public-late-final-fields-without-initializers
 [nullable type]: /null-safety/understanding-null-safety#using-nullable-types