docs: included doc comments where possible

lib/game/components/controlled_ball.dart

@@ -49,6 +49,8 @@ class BallController extends ComponentController<Ball>
   /// {@macro ball_controller}
   BallController(Ball ball) : super(ball);
 
+  /// Event triggered when the ball is lost.
+  // TODO(alestiago): Refactor using behaviors.
   void lost() {
     component.shouldRemove = true;
   }

lib/game/components/google_word/behaviors/google_word_bonus_behavior.dart

@@ -3,6 +3,7 @@ import 'package:pinball/game/game.dart';
 import 'package:pinball_components/pinball_components.dart';
 import 'package:pinball_flame/pinball_flame.dart';
 
+/// Adds a [GameBonus.googleWord] when all [GoogleLetter]s are activated.
 class GoogleWordBonusBehavior extends Component
     with HasGameRef<PinballGame>, ParentIsA<GoogleWord> {
   @override
@@ -11,6 +12,9 @@ class GoogleWordBonusBehavior extends Component
 
     final googleLetters = parent.children.whereType<GoogleLetter>();
     for (final letter in googleLetters) {
+      // TODO(alestiago): Refactor subscription management once the following is
+      // merged:
+      // https://github.com/flame-engine/flame/pull/1538
       letter.bloc.stream.listen((_) {
         final achievedBonus = googleLetters
             .every((letter) => letter.bloc.state == GoogleLetterState.active);

packages/pinball_components/lib/src/components/alien_bumper/alien_bumper.dart

@@ -75,6 +75,7 @@ class AlienBumper extends BodyComponent with InitialPosition {
 
   // TODO(alestiago): Consider refactoring once the following is merged:
   // https://github.com/flame-engine/flame/pull/1538
+  // ignore: public_member_api_docs
   final AlienBumperCubit bloc;
 
   @override

packages/pinball_components/lib/src/components/alien_bumper/behaviors/alien_bumper_ball_contact_behavior.dart

@@ -2,6 +2,9 @@ import 'package:flame_forge2d/flame_forge2d.dart';
 import 'package:pinball_components/pinball_components.dart';
 import 'package:pinball_flame/pinball_flame.dart';
 
+// TODO(alestiago): Evaluate if there is any useful documentation that could
+// be added to this class.
+// ignore: public_member_api_docs
 class AlienBumperBallContactBehavior extends ContactBehavior<AlienBumper> {
   @override
   void beginContact(Object other, Contact contact) {

packages/pinball_components/lib/src/components/alien_bumper/cubit/alien_bumper_cubit.dart

@@ -2,13 +2,19 @@ import 'package:bloc/bloc.dart';
 
 part 'alien_bumper_state.dart';
 
+// TODO(alestiago): Evaluate if there is any useful documentation that could
+// be added to this class.
+// ignore: public_member_api_docs
 class AlienBumperCubit extends Cubit<AlienBumperState> {
+  // ignore: public_member_api_docs
   AlienBumperCubit() : super(AlienBumperState.active);
 
+  /// Event added when a bumper contacts with a ball.
   void onBallContacted() {
     emit(AlienBumperState.inactive);
   }
 
+  /// Event added when a bumper finishes blinking.
   void onBlinked() {
     emit(AlienBumperState.active);
   }

packages/pinball_components/lib/src/components/google_letter/behaviors/google_letter_ball_contact_behavior.dart

@@ -2,6 +2,9 @@ import 'package:flame_forge2d/flame_forge2d.dart';
 import 'package:pinball_components/pinball_components.dart';
 import 'package:pinball_flame/pinball_flame.dart';
 
+// TODO(alestiago): Evaluate if there is any useful documentation that could
+// be added to this class.
+// ignore: public_member_api_docs
 class GoogleLetterBallContactBehavior extends ContactBehavior<GoogleLetter> {
   @override
   void beginContact(Object other, Contact contact) {

packages/pinball_components/lib/src/components/google_letter/cubit/google_letter_cubit.dart

@@ -2,13 +2,19 @@ import 'package:bloc/bloc.dart';
 
 part 'google_letter_state.dart';
 
+// TODO(alestiago): Evaluate if there is any useful documentation that could
+// be added to this class.
+// ignore: public_member_api_docs
 class GoogleLetterCubit extends Cubit<GoogleLetterState> {
+  // ignore: public_member_api_docs
   GoogleLetterCubit() : super(GoogleLetterState.inactive);
 
+  /// Event added when a letter contacts with a ball.
   void onBallContacted() {
     emit(GoogleLetterState.active);
   }
 
+  /// Event added when a letter should return to its initial configuration.
   void onReset() {
     emit(GoogleLetterState.inactive);
   }

packages/pinball_components/lib/src/components/google_letter/cubit/google_letter_state.dart

@@ -1,7 +1,10 @@
 part of 'google_letter_cubit.dart';
 
+/// Indicates the [GoogleLetterCubit]'s current state.
 enum GoogleLetterState {
+  /// A lit up letter.
   active,
 
+  /// A dimmed letter.
   inactive,
 }

packages/pinball_components/lib/src/components/google_letter/google_letter.dart

@@ -1,7 +1,5 @@
 import 'package:flame/components.dart';
-import 'package:flame/effects.dart';
 import 'package:flame_forge2d/flame_forge2d.dart';
-import 'package:flutter/material.dart';
 import 'package:pinball_components/pinball_components.dart';
 import 'package:pinball_components/src/components/google_letter/behaviors/behaviors.dart';
 import 'package:pinball_flame/pinball_flame.dart';
@@ -26,6 +24,7 @@ class GoogleLetter extends BodyComponent with InitialPosition {
 
   // TODO(alestiago): Consider refactoring once the following is merged:
   // https://github.com/flame-engine/flame/pull/1538
+  // ignore: public_member_api_docs
   final GoogleLetterCubit bloc;
 
   @override

packages/pinball_components/lib/src/components/sparky_bumper/behaviors/sparky_bumper_ball_contact_behavior.dart

@@ -2,6 +2,9 @@ import 'package:flame_forge2d/flame_forge2d.dart';
 import 'package:pinball_components/pinball_components.dart';
 import 'package:pinball_flame/pinball_flame.dart';
 
+// TODO(alestiago): Evaluate if there is any useful documentation that could
+// be added to this class.
+// ignore: public_member_api_docs
 class SparkyBumperBallContactBehavior extends ContactBehavior<SparkyBumper> {
   @override
   void beginContact(Object other, Contact contact) {

packages/pinball_components/lib/src/components/sparky_bumper/cubit/sparky_bumper_cubit.dart

@@ -2,13 +2,19 @@ import 'package:bloc/bloc.dart';
 
 part 'sparky_bumper_state.dart';
 
+// TODO(alestiago): Evaluate if there is any useful documentation that could
+// be added to this class.
+// ignore: public_member_api_docs
 class SparkyBumperCubit extends Cubit<SparkyBumperState> {
+  // ignore: public_member_api_docs
   SparkyBumperCubit() : super(SparkyBumperState.active);
 
+  /// Event added when a bumper contacts with a ball.
   void onBallContacted() {
     emit(SparkyBumperState.inactive);
   }
 
+  /// Event added when a bumper finishes blinking.
   void onBlinked() {
     emit(SparkyBumperState.active);
   }

packages/pinball_components/lib/src/components/sparky_bumper/sparky_bumper.dart

@@ -91,6 +91,7 @@ class SparkyBumper extends BodyComponent with InitialPosition {
 
   // TODO(alestiago): Consider refactoring once the following is merged:
   // https://github.com/flame-engine/flame/pull/1538
+  // ignore: public_member_api_docs
   final SparkyBumperCubit bloc;
 
   @override

packages/pinball_flame/lib/src/contact_behavior.dart

@@ -3,6 +3,15 @@ import 'package:flame_forge2d/flame_forge2d.dart';
 import 'package:flutter/material.dart';
 import 'package:pinball_flame/pinball_flame.dart';
 
+/// Adds a new [ContactCallbacks] to the parent.
+///
+/// This is a convenience class for adding a [ContactCallbacks] to the parent.
+/// In constract with just adding a [ContactCallbacks] to the parent's userData,
+/// this class respects the previous [ContactCallbacks], if any, in the parent.
+/// Hence, it avoids overriding any previous [ContactCallbacks] in the parent.
+///
+/// It does so by grouping the [ContactCallbacks] in a [_ContactCallbacksGroup],
+/// and resetting the parent's userData accordingly.
 // TODO(alestiago): Make use of generics to infer the type of the contact.
 // https://github.com/VGVentures/pinball/pull/234#discussion_r859182267
 abstract class ContactBehavior<T extends BodyComponent> extends Component