From ccd724909c7600094d3fbe171c2a33fe77b661be Mon Sep 17 00:00:00 2001
From: RuiAlonso <rui.alonso@verygood.ventures>
Date: Thu, 17 Mar 2022 09:53:01 +0100
Subject: [PATCH] doc: documented leaderboard bloc

---
 lib/leaderboard/bloc/leaderboard_bloc.dart  | 10 +++++++--
 lib/leaderboard/bloc/leaderboard_event.dart |  4 ++++
 lib/leaderboard/bloc/leaderboard_state.dart | 23 ++++++++++++++++++++-
 3 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/lib/leaderboard/bloc/leaderboard_bloc.dart b/lib/leaderboard/bloc/leaderboard_bloc.dart
index 9a4742f0..74198d41 100644
--- a/lib/leaderboard/bloc/leaderboard_bloc.dart
+++ b/lib/leaderboard/bloc/leaderboard_bloc.dart
@@ -17,7 +17,13 @@ class LeaderboardRepository {
   }
 }
 
+/// {@template leaderboard_bloc}
+/// Bloc for manage events on leaderboard.
+///
+/// Uses a [LeaderboardRepository] to request and update players participations.
+/// {@endtemplate}
 class LeaderboardBloc extends Bloc<LeaderboardEvent, LeaderboardState> {
+  /// {@macro leaderboard_bloc}
   LeaderboardBloc(this._leaderboardRepository)
       : super(const LeaderboardState()) {
     on<Top10Fetched>(_onTop10Fetched);
@@ -26,7 +32,7 @@ class LeaderboardBloc extends Bloc<LeaderboardEvent, LeaderboardState> {
 
   final LeaderboardRepository _leaderboardRepository;
 
-  FutureOr<void> _onTop10Fetched(
+  Future<void> _onTop10Fetched(
     Top10Fetched event,
     Emitter<LeaderboardState> emit,
   ) async {
@@ -46,7 +52,7 @@ class LeaderboardBloc extends Bloc<LeaderboardEvent, LeaderboardState> {
     }
   }
 
-  FutureOr<void> _onLeaderboardEntryAdded(
+  Future<void> _onLeaderboardEntryAdded(
     LeaderboardEntryAdded event,
     Emitter<LeaderboardState> emit,
   ) async {
diff --git a/lib/leaderboard/bloc/leaderboard_event.dart b/lib/leaderboard/bloc/leaderboard_event.dart
index 4c06eabd..c14996bd 100644
--- a/lib/leaderboard/bloc/leaderboard_event.dart
+++ b/lib/leaderboard/bloc/leaderboard_event.dart
@@ -1,5 +1,6 @@
 part of 'leaderboard_bloc.dart';
 
+/// Represents the events available for [LeaderboardBloc].
 abstract class LeaderboardEvent extends Equatable {
   const LeaderboardEvent();
 
@@ -7,13 +8,16 @@ abstract class LeaderboardEvent extends Equatable {
   List<Object?> get props => [];
 }
 
+/// Request the top 10 from leaderboard.
 class Top10Fetched extends LeaderboardEvent {
   const Top10Fetched();
 }
 
+/// Insert new entry at leaderboard when user ends game.
 class LeaderboardEntryAdded extends LeaderboardEvent {
   const LeaderboardEntryAdded({required this.entry});
 
+  /// Current entry to persist at leaderboard.
   final LeaderboardEntry entry;
 
   @override
diff --git a/lib/leaderboard/bloc/leaderboard_state.dart b/lib/leaderboard/bloc/leaderboard_state.dart
index 458a513b..5e775b4b 100644
--- a/lib/leaderboard/bloc/leaderboard_state.dart
+++ b/lib/leaderboard/bloc/leaderboard_state.dart
@@ -1,8 +1,22 @@
 part of 'leaderboard_bloc.dart';
 
-enum LeaderboardStatus { loading, success, error }
+/// Defines request status
+enum LeaderboardStatus {
+  /// While loading request.
+  loading,
 
+  /// Everything run ok and received response.
+  success,
+
+  /// There were some error on request.
+  error,
+}
+
+/// {@template leaderboard_state}
+/// Represents the state of the leaderboard.
+/// {@endtemplate}
 class LeaderboardState extends Equatable {
+  /// {@macro leaderboard_state}
   const LeaderboardState({
     this.status = LeaderboardStatus.loading,
     this.ranking = const LeaderboardRanking(
@@ -12,13 +26,20 @@ class LeaderboardState extends Equatable {
     this.leaderboard = const [],
   });
 
+  /// The current [LeaderboardStatus] of the state
   final LeaderboardStatus status;
+
+  /// Ranking for the user.
   final LeaderboardRanking ranking;
+
+  /// List of users at leaderboard.
   final List<LeaderboardEntry> leaderboard;
 
   @override
   List<Object> get props => [status, ranking, leaderboard];
 
+  /// Method to copy [LeaderboardState] modifying only explicit params and
+  /// keeping others.
   LeaderboardState copyWith({
     LeaderboardStatus? status,
     LeaderboardRanking? ranking,