Update Align docs (#27260)

packages/flutter/lib/src/painting/alignment.dart

@@ -154,7 +154,15 @@ abstract class AlignmentGeometry {
 /// respect to the rectangle and vertically below the bottom of the rectangle by
 /// the height of the rectangle.
 ///
-/// [Alignment] use visual coordinates, which means increasing [x] moves the
+/// `Alignment(0.0, -0.5)` represents a point that is horizontally centered with
+/// respect to the rectangle and vertically half way between the top edge and
+/// the center.
+///
+/// `Alignment(x, y)` in a rectangle with height h and width w describes
+/// the point (x * w/2 + w/2, y * h/2 + h/2) in the coordinate system of the
+/// rectangle.
+///
+/// [Alignment] uses visual coordinates, which means increasing [x] moves the
 /// point from left to right. To support layouts with a right-to-left
 /// [TextDirection], consider using [AlignmentDirectional], in which the
 /// direction the point moves when increasing the horizontal value depends on

packages/flutter/lib/src/widgets/basic.dart

@@ -1528,6 +1528,49 @@ class Padding extends SingleChildRenderObjectWidget {
 /// dimension and the size factor. For example if widthFactor is 2.0 then
 /// the width of this widget will always be twice its child's width.
 ///
+/// ## How it works
+///
+/// The [alignment] property describes a point in the `child`'s coordinate system
+/// and a different point in the coordinate system of this widget. The [Align]
+/// widget positions the `child` such that both points are lined up on top of
+/// each other.
+///
+/// {@tool sample}
+/// The [FractionalOffset] used in the following example defines two points:
+///
+///   * (0.2 * width of red [Container], 0.6 * height of red [Container]) = (8.0, 24.0)
+///     in the coordinate system of the red container.
+///   * (0.2 * width of [Align], 0.6 * height of [Align]) = (20.0, 60.0) in the
+///     coordinate system of the [Align] widget.
+///
+/// The [Align] widget positions the red [Container] such that the two points are on
+/// top of each other. In this example, the top left of the red [Container] will
+/// be placed at (20.0, 60.0) - (8.0, 24.0) = (12.0, 36.0) from the top left of
+/// the [Align] widget.
+///
+/// Using [Alignment] instead of [FractionalOffset] for [alignment] just changes
+/// the way how the two points for alignment are calculated.
+///
+/// ```dart
+/// Center(
+///   child: Container(
+///     height: 100.0,
+///     width: 100.0,
+///     color: Colors.yellow
+///     child: Align(
+///       alignment: FractionalOffset(0.2, 0.6),
+///       child: Container(
+///         height: 40.0,
+///         width: 40.0,
+///         color: Colors.red,
+///       ),
+///     ),
+///   ),
+/// );
+///
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [CustomSingleChildLayout], which uses a delegate to control the layout of