From d24b19e757671996298752c6df91d271846d0eb7 Mon Sep 17 00:00:00 2001 From: rportet Date: Sat, 8 Jun 2024 19:17:10 +0200 Subject: [PATCH] more and more documentation, again --- Qwirkle/QwirkleClassLibrary/Boards/Board.cs | 4 +- Qwirkle/QwirkleClassLibrary/Boards/Cell.cs | 142 +++++++++--------- Qwirkle/QwirkleClassLibrary/Games/Game.cs | 7 +- Qwirkle/QwirkleClassLibrary/Games/IPlayer.cs | 36 ++--- .../Persistences/GamePersistenceXml.cs | 55 ++++--- .../LeaderboardPersistenceJson.cs | 44 ++++-- 6 files changed, 160 insertions(+), 128 deletions(-) diff --git a/Qwirkle/QwirkleClassLibrary/Boards/Board.cs b/Qwirkle/QwirkleClassLibrary/Boards/Board.cs index 1a03e1e..700430e 100644 --- a/Qwirkle/QwirkleClassLibrary/Boards/Board.cs +++ b/Qwirkle/QwirkleClassLibrary/Boards/Board.cs @@ -60,9 +60,9 @@ namespace QwirkleClassLibrary.Boards } /// - /// This method is used to check if a cell in the board whether it already contains a tile or not. + /// This method is used to check if a cell in the board whether already contains a tile or not. /// - /// Returns a boolean : true if the cell doesn't contain any tile, false if it already contains a tile. + /// Returns a boolean : true if the cell doesn't contain any tile, false if already contains a tile. public bool HasOccupiedCase() { foreach (var cell in cells) diff --git a/Qwirkle/QwirkleClassLibrary/Boards/Cell.cs b/Qwirkle/QwirkleClassLibrary/Boards/Cell.cs index e1f9c03..0301074 100644 --- a/Qwirkle/QwirkleClassLibrary/Boards/Cell.cs +++ b/Qwirkle/QwirkleClassLibrary/Boards/Cell.cs @@ -4,92 +4,94 @@ using System.Runtime.CompilerServices; using System.Runtime.Serialization; using QwirkleClassLibrary.Tiles; -namespace QwirkleClassLibrary.Boards; - -/// -/// Our board is made with a list of this class. It can stock infos such as its position on the board and the tile it contains. -/// -[DataContract] -public class Cell : INotifyPropertyChanged +namespace QwirkleClassLibrary.Boards { - public event PropertyChangedEventHandler? PropertyChanged; - - [DataMember] - private readonly int x; - - [DataMember] - private readonly int y; - - [DataMember] - public Tile? Tile { get; private set;} /// - /// This is the constructor for a Cell. + /// Our board is made with a list of this class. It can stock infos such as its position on the board and the tile it contains. /// - /// The x attribute of the cell. - /// The y attribute of the cell. - /// Throw an exception if the x or y attribute is negative. - public Cell(int x, int y) + [DataContract] + public class Cell : INotifyPropertyChanged { - if (x < 0 || y < 0) - { - throw new ArgumentException(x.ToString() + y.ToString()); - } + public event PropertyChangedEventHandler? PropertyChanged; - this.x = x; - this.y = y; - } + [DataMember] + private readonly int x; - /// - /// A getter for the position of the cell on the x-axis. - /// - /// The position of the cell on the x-axis. - public int GetX - { - get { return x; } - } + [DataMember] + private readonly int y; - /// - /// A getter for the position of the cell on the y-axis. - /// - /// The position of the cell on the y-axis. - public int GetY - { - get { return y; } - } + [DataMember] + public Tile? Tile { get; private set; } - /// - /// Check if the Cell whether is empty or contains a tile. - /// - /// True if the cell is empty, false if the cell contains a tile. - public bool IsFree - { - get { return Tile! == null!; } - } + /// + /// This is the constructor for a Cell. + /// + /// The x attribute of the cell. + /// The y attribute of the cell. + /// Throw an exception if the x or y attribute is negative. + public Cell(int x, int y) + { + if (x < 0 || y < 0) + { + throw new ArgumentException(x.ToString() + y.ToString()); + } + this.x = x; + this.y = y; + } - /// - /// A setter for the tile in the cell. - /// - /// The tile the player want to add in the cell. - /// True if added succefully (if the cell didn't already contain a tile), false if there already was a tile in this cell. - public bool SetTile(Tile addedTile) - { - if (Tile! == null!) + /// + /// A getter for the position of the cell on the x-axis. + /// + /// The position of the cell on the x-axis. + public int GetX + { + get { return x; } + } + + /// + /// A getter for the position of the cell on the y-axis. + /// + /// The position of the cell on the y-axis. + public int GetY { + get { return y; } + } - Tile = addedTile; - OnPropertyChanged(nameof(Tile)); - return true; + /// + /// Checks if the Cell whether is empty or contains a tile. + /// + /// True if the cell is empty, false if the cell contains a tile. + public bool IsFree + { + get { return Tile! == null!; } } - else + + + /// + /// A setter for the tile in the cell. + /// + /// The tile the player want to add in the cell. + /// True if added succefully (if the cell didn't already contain a tile), false if there already was a tile in this cell. + public bool SetTile(Tile addedTile) { - return false; + if (Tile! == null!) + { + + Tile = addedTile; + OnPropertyChanged(nameof(Tile)); + return true; + } + else + { + return false; + } } - } - protected virtual void OnPropertyChanged([CallerMemberName] string? propertyName = null) - { - PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName)); + protected virtual void OnPropertyChanged([CallerMemberName] string? propertyName = null) + { + PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName)); + } } } \ No newline at end of file diff --git a/Qwirkle/QwirkleClassLibrary/Games/Game.cs b/Qwirkle/QwirkleClassLibrary/Games/Game.cs index 615734b..268ca34 100644 --- a/Qwirkle/QwirkleClassLibrary/Games/Game.cs +++ b/Qwirkle/QwirkleClassLibrary/Games/Game.cs @@ -122,7 +122,12 @@ namespace QwirkleClassLibrary.Games OnPlayerNotified(new AddPlayerNotifiedEventArgs("Players were correctly added.")); return true; } - + /// + /// This function is used to check if the player name that the user has entered meets the criteria set by the application. + /// + /// A list that contains all the names entered when the game was started. + /// The position of the name we want to check in this list. + /// boolean true if everything is okay, false if there was a problem in the player name. public bool CheckPlayerTag(List playersTag, int pos) { if (string.IsNullOrWhiteSpace(playersTag[pos])) diff --git a/Qwirkle/QwirkleClassLibrary/Games/IPlayer.cs b/Qwirkle/QwirkleClassLibrary/Games/IPlayer.cs index 26ce37f..b273bc8 100644 --- a/Qwirkle/QwirkleClassLibrary/Games/IPlayer.cs +++ b/Qwirkle/QwirkleClassLibrary/Games/IPlayer.cs @@ -3,30 +3,32 @@ using QwirkleClassLibrary.Boards; using QwirkleClassLibrary.Players; using QwirkleClassLibrary.Tiles; -namespace QwirkleClassLibrary.Games; - -/// -/// This interface is used for all methods related to the player, such as the moves he can make. -/// -public interface IPlayer +namespace QwirkleClassLibrary.Games { - public Player CreatePlayer(string playerTag); - public string SetNextPlayer(); + /// + /// This interface is used for all methods related to the player, such as the moves he can make. + /// + public interface IPlayer + { + public Player CreatePlayer(string playerTag); + + public string SetNextPlayer(); - public string SetFirstPlayer(ReadOnlyCollection playingPlayers); + public string SetFirstPlayer(ReadOnlyCollection playingPlayers); - public bool PlaceTile(Player player, Tile tile, int x, int y); + public bool PlaceTile(Player player, Tile tile, int x, int y); - public bool DrawTiles(Player player); + public bool DrawTiles(Player player); - public bool SwapTiles(Player player, List tilesToSwap); + public bool SwapTiles(Player player, List tilesToSwap); - public int GetPlayerScore(Player player, ReadOnlyCollection cellsPlayed, Board b); + public int GetPlayerScore(Player player, ReadOnlyCollection cellsPlayed, Board b); - int CalculateAdjacentScore(Cell cell, Board b, ReadOnlyCollection cellsPlayed, Tuple orientation, - ref int nbCellsInLine, ref int nbCellsInPerpLine, ref List checkedCells); + int CalculateAdjacentScore(Cell cell, Board b, ReadOnlyCollection cellsPlayed, Tuple orientation, + ref int nbCellsInLine, ref int nbCellsInPerpLine, ref List checkedCells); - int CalculateLineScore(ReadOnlyCollection cellsPlayed, Cell cell, Tuple direction, - Tuple orientation, ref int nbCellsInLine, ref int nbCellsInPerpLine, ref List checkedCells); + int CalculateLineScore(ReadOnlyCollection cellsPlayed, Cell cell, Tuple direction, + Tuple orientation, ref int nbCellsInLine, ref int nbCellsInPerpLine, ref List checkedCells); + } } \ No newline at end of file diff --git a/Qwirkle/QwirkleClassLibrary/Persistences/GamePersistenceXml.cs b/Qwirkle/QwirkleClassLibrary/Persistences/GamePersistenceXml.cs index 564134a..9f9cf5b 100644 --- a/Qwirkle/QwirkleClassLibrary/Persistences/GamePersistenceXml.cs +++ b/Qwirkle/QwirkleClassLibrary/Persistences/GamePersistenceXml.cs @@ -1,36 +1,47 @@ using System.Runtime.Serialization; using QwirkleClassLibrary.Games; -namespace QwirkleClassLibrary.Persistences; - -public class GamePersistenceXml : IGamePersistence +namespace QwirkleClassLibrary.Persistences { - public void SaveGame(Game game) + /// + /// This class takes care of managing persistence with regard to the information of the current game, allowing the last game played to be resumed even when returning to the menu or exiting the application. + /// + public class GamePersistenceXml : IGamePersistence { - var serializer = new DataContractSerializer(typeof(Game), - new DataContractSerializerSettings() { PreserveObjectReferences = true }); - - using (Stream writer = File.Create("Game.xml")) + /// + /// The main purpose of this method is to save the data from the game when the user quits the app, so players can continue it later. + /// + /// + public void SaveGame(Game game) { - serializer.WriteObject(writer, game); - } - } + var serializer = new DataContractSerializer(typeof(Game), + new DataContractSerializerSettings() { PreserveObjectReferences = true }); - public Game LoadGame() - { - var serializer = new DataContractSerializer(typeof(Game)); - - try - { - using (Stream reader = File.OpenRead("Game.xml")) + using (Stream writer = File.Create("Game.xml")) { - var newGame = serializer.ReadObject(reader) as Game; - return newGame!; + serializer.WriteObject(writer, game); } } - catch + /// + /// This method is used to retrieve the information needed to resume the last game launched on the application. + /// + /// A Game. + public Game LoadGame() { - return new Game(); + var serializer = new DataContractSerializer(typeof(Game)); + + try + { + using (Stream reader = File.OpenRead("Game.xml")) + { + var newGame = serializer.ReadObject(reader) as Game; + return newGame!; + } + } + catch + { + return new Game(); + } } } } \ No newline at end of file diff --git a/Qwirkle/QwirkleClassLibrary/Persistences/LeaderboardPersistenceJson.cs b/Qwirkle/QwirkleClassLibrary/Persistences/LeaderboardPersistenceJson.cs index 82b41c1..658090c 100644 --- a/Qwirkle/QwirkleClassLibrary/Persistences/LeaderboardPersistenceJson.cs +++ b/Qwirkle/QwirkleClassLibrary/Persistences/LeaderboardPersistenceJson.cs @@ -1,27 +1,39 @@ using System.Runtime.Serialization.Json; using QwirkleClassLibrary.Players; -namespace QwirkleClassLibrary.Persistences; - -public class LeaderboardPersistenceJson : ILeaderboardPersistence +namespace QwirkleClassLibrary.Persistences { - public void SaveLeaderboard(Leaderboard leaderboard) + /// + /// This is the persistence class for the leaderboard : it is in charge of managing all the parameters necessary for the backup and recovery of data concerning the leaderboard. + /// + public class LeaderboardPersistenceJson : ILeaderboardPersistence { - var serializer = new DataContractJsonSerializer(typeof(Leaderboard)); - - using (Stream writer = File.Create("Leaderboard.json")) + /// + /// As the name suggest, this class is used to save the data from the leaderboard. + /// + /// The current leaderboard we want to save data from. + public void SaveLeaderboard(Leaderboard leaderboard) { - serializer.WriteObject(writer, leaderboard); - } - } + var serializer = new DataContractJsonSerializer(typeof(Leaderboard)); - public Leaderboard LoadLeaderboard() - { - var serializer = new DataContractJsonSerializer(typeof(Leaderboard)); - - using (Stream reader = File.OpenRead("Leaderboard.json")) + using (Stream writer = File.Create("Leaderboard.json")) + { + serializer.WriteObject(writer, leaderboard); + } + } + /// + /// This method is used to load the leaderboard into the app when the application starts. + /// + /// Leaderboard + /// + public Leaderboard LoadLeaderboard() { - return serializer.ReadObject(reader) as Leaderboard ?? throw new InvalidOperationException(); + var serializer = new DataContractJsonSerializer(typeof(Leaderboard)); + + using (Stream reader = File.OpenRead("Leaderboard.json")) + { + return serializer.ReadObject(reader) as Leaderboard ?? throw new InvalidOperationException(); + } } } } \ No newline at end of file