From e9776a8d5ef6f643ad04d2ed49856475d059918d Mon Sep 17 00:00:00 2001
From: Alejandro Santiago <dev@alestiago.com>
Date: Thu, 10 Mar 2022 13:38:56 +0000
Subject: [PATCH] docs: included missing documentation (#29)

* chore: ignored lint rue

* docs: documented ball.dart

* docs: ignored lint rule

* docs: documented wall.dart

* docs: documented game_over_dialog.dart

* docs: fixed typo

* docs: included TODO comments
---
 lib/game/components/ball.dart               | 17 ++++++++++++-----
 lib/game/components/flipper.dart            |  1 +
 lib/game/components/wall.dart               |  6 ++++++
 lib/game/view/widgets/game_over_dialog.dart |  5 +++++
 lib/theme/cubit/theme_cubit.dart            |  3 +++
 lib/theme/cubit/theme_state.dart            |  3 +++
 6 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/lib/game/components/ball.dart b/lib/game/components/ball.dart
index aeb9be69..cdd1296c 100644
--- a/lib/game/components/ball.dart
+++ b/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;
 
diff --git a/lib/game/components/flipper.dart b/lib/game/components/flipper.dart
index bd071b93..2797b07c 100644
--- a/lib/game/components/flipper.dart
+++ b/lib/game/components/flipper.dart
@@ -148,6 +148,7 @@ class Flipper extends BodyComponent 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
diff --git a/lib/game/components/wall.dart b/lib/game/components/wall.dart
index b784b8cb..f5a15af5 100644
--- a/lib/game/components/wall.dart
+++ b/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),
diff --git a/lib/game/view/widgets/game_over_dialog.dart b/lib/game/view/widgets/game_over_dialog.dart
index 586d6c56..9d1c61b0 100644
--- a/lib/game/view/widgets/game_over_dialog.dart
+++ b/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
diff --git a/lib/theme/cubit/theme_cubit.dart b/lib/theme/cubit/theme_cubit.dart
index 7ba79e59..94eba4a6 100644
--- a/lib/theme/cubit/theme_cubit.dart
+++ b/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';
diff --git a/lib/theme/cubit/theme_state.dart b/lib/theme/cubit/theme_state.dart
index 13b3ea5f..078f5c84 100644
--- a/lib/theme/cubit/theme_state.dart
+++ b/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 {