Merge branch 'main' into feat/flipper-placeholder-art

lib/game/components/ball.dart

@@ -13,24 +13,26 @@ class Ball extends PositionBodyComponent<PinballGame, SpriteComponent>
   Ball({
     required Vector2 position,
   })  : _position = position,
-        super(size: ballSize);
-
-  static final ballSize = Vector2.all(2);
+        super(size: Vector2.all(2));
 
+  /// The initial position of the [Ball] body.
   final Vector2 _position;
 
+  /// Asset location of the sprite that renders with the [Ball].
+  ///
+  /// Sprite is preloaded by [PinballGameAssetsX].
   static const spritePath = 'components/ball.png';
 
   @override
   Future<void> onLoad() async {
     await super.onLoad();
     final sprite = await gameRef.loadSprite(spritePath);
-    positionComponent = SpriteComponent(sprite: sprite, size: ballSize);
+    positionComponent = SpriteComponent(sprite: sprite, size: size);
   }
 
   @override
   Body createBody() {
-    final shape = CircleShape()..radius = ballSize.x / 2;
+    final shape = CircleShape()..radius = size.x / 2;
 
     final fixtureDef = FixtureDef(shape)..density = 1;
 
@@ -42,6 +44,11 @@ class Ball extends PositionBodyComponent<PinballGame, SpriteComponent>
     return world.createBody(bodyDef)..createFixture(fixtureDef);
   }
 
+  /// Removes the [Ball] from a [PinballGame]; spawning a new [Ball] if
+  /// any are left.
+  ///
+  /// Triggered by [BottomWallBallContactCallback] when the [Ball] falls into
+  /// a [BottomWall].
   void lost() {
     shouldRemove = true;
 

lib/game/components/flipper.dart

@@ -160,6 +160,7 @@ class Flipper extends PositionBodyComponent with KeyboardHandler {
 
   // TODO(erickzanardo): Remove this once the issue is solved:
   // https://github.com/flame-engine/flame/issues/1417
+  // ignore: public_member_api_docs
   final Completer hasMounted = Completer<void>();
 
   @override

lib/game/components/wall.dart

@@ -6,13 +6,18 @@ import 'package:pinball/game/components/components.dart';
 /// {@template wall}
 /// A continuos generic and [BodyType.static] barrier that divides a game area.
 /// {@endtemplate}
+// TODO(alestiago): Remove [Wall] for [Pathway.straight].
 class Wall extends BodyComponent {
+  /// {@macro wall}
   Wall({
     required this.start,
     required this.end,
   });
 
+  /// The [start] of the [Wall].
   final Vector2 start;
+
+  /// The [end] of the [Wall].
   final Vector2 end;
 
   @override
@@ -39,6 +44,7 @@ class Wall extends BodyComponent {
 /// [BottomWallBallContactCallback].
 /// {@endtemplate}
 class BottomWall extends Wall {
+  /// {@macro bottom_wall}
   BottomWall(Forge2DGame game)
       : super(
           start: game.screenToWorld(game.camera.viewport.effectiveSize),

lib/game/view/widgets/game_over_dialog.dart

@@ -1,6 +1,11 @@
 import 'package:flutter/material.dart';
+import 'package:pinball/game/game.dart';
 
+/// {@template game_over_dialog}
+/// [Dialog] displayed when the [PinballGame] is over.
+/// {@endtemplate}
 class GameOverDialog extends StatelessWidget {
+  /// {@macro game_over_dialog}
   const GameOverDialog({Key? key}) : super(key: key);
 
   @override

lib/theme/cubit/theme_cubit.dart

@@ -1,3 +1,6 @@
+// ignore_for_file: public_member_api_docs
+// TODO(allisonryan0002): Document this section when the API is stable.
+
 import 'package:bloc/bloc.dart';
 import 'package:equatable/equatable.dart';
 import 'package:pinball_theme/pinball_theme.dart';

lib/theme/cubit/theme_state.dart

@@ -1,3 +1,6 @@
+// ignore_for_file: public_member_api_docs
+// TODO(allisonryan0002): Document this section when the API is stable.
+
 part of 'theme_cubit.dart';
 
 class ThemeState extends Equatable {