Updated use cases documentation.

8 files changed, 268 insertions, 96 deletions

diff --git a/doc/Makefile b/doc/Makefile
index d2799a8..e849a01 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -5,7 +5,7 @@ outputFolder = out
 
 texFiles = tex/tfg.tex tex/introduction.tex tex/planification.tex tex/implementation.tex tex/systemAnalysis.tex tex/systemDesign.tex tex/biber.bib
 
-diagramImgs = diagrams/gameRepresentation.png diagrams/gtpEngine.png diagrams/modules.png diagrams/planificationWorkPlanEngine.png diagrams/planificationWorkPlanGame.png diagrams/sgfModule.png diagrams/useCases.png diagrams/analysisClasses.png diagrams/useCase_useAsBackend.png diagrams/interfaces.png
+diagramImgs = diagrams/gameRepresentation.png diagrams/gtpEngine.png diagrams/modules.png diagrams/planificationWorkPlanEngine.png diagrams/planificationWorkPlanGame.png diagrams/sgfModule.png diagrams/useCases.png diagrams/analysisClasses.png diagrams/useCase_generateAMove.png diagrams/useCase_useAsBackend.png diagrams/useCase_playAMatch.png diagrams/interfaces.png
 
 all: $(docName).pdf
 
diff --git a/doc/diagrams/useCase_generateAMove.puml b/doc/diagrams/useCase_generateAMove.puml
new file mode 100644
index 0000000..fa76edb
--- /dev/null
+++ b/doc/diagrams/useCase_generateAMove.puml
@@ -0,0 +1,24 @@
+@startuml
+
+!include skinparams.puml
+
+actor "GUI program / Human user" as user
+
+boundary "Engine CLI" as cli
+control "Play a stone" as playStone
+control "Think next move" as think
+entity "Board state" as state
+
+loop until desired board is set
+    user -> cli : play stone
+    cli -> playStone
+    playStone -> state
+    cli <- state
+end
+
+user -> cli : ask for move
+cli -> think
+think -> state
+cli <- state : Show move
+
+@enduml
diff --git a/doc/diagrams/useCase_playAMatch.puml b/doc/diagrams/useCase_playAMatch.puml
new file mode 100644
index 0000000..65d1517
--- /dev/null
+++ b/doc/diagrams/useCase_playAMatch.puml
@@ -0,0 +1,20 @@
+@startuml
+
+!include skinparams.puml
+
+actor "Player" as player
+
+boundary "Game CLI" as cli
+control "Play a stone" as playStone
+control "Show board" as showBoard
+entity "Board state" as state
+
+loop until game ends
+    player -> cli
+    cli -> playStone
+    playStone -> state
+    showBoard <- state
+    cli <- showBoard
+end
+
+@enduml
diff --git a/doc/diagrams/useCase_useAsBackend.puml b/doc/diagrams/useCase_useAsBackend.puml
index 3f1cece..9076769 100644
--- a/doc/diagrams/useCase_useAsBackend.puml
+++ b/doc/diagrams/useCase_useAsBackend.puml
@@ -2,22 +2,31 @@
 
 !include skinparams.puml
 
+actor "Opponent" as opponent
 actor "GUI Program" as program
 
-boundary "Set board state" as setState
-control "State set to represent the needed board" as setStateEngine
+boundary "Engine CLI" as cli
+control "Play a stone" as playStone
+control "Think next move" as think
 entity "Board state" as state
-boundary "Move is asked for" as ask
-control "Engine thinks next move" as think
-boundary "Move is suggested" as suggestion
 
-program -> setState
-setState -> setStateEngine
-setStateEngine -> state
-state -> ask
-program -> ask
-ask -> think
-think -> suggestion
-program -> suggestion
+loop until starting board is set
+    program -> cli : play stone
+    cli -> playStone
+    playStone -> state
+    cli <- state
+end
+
+loop until game ends
+    program -> cli : ask for move
+    cli -> think
+    think -> state
+    cli <- state : Show move
+    opponent -> program : give input
+    program -> cli : play stone
+    cli -> playStone
+    playStone -> state
+    cli <- state
+end
 
 @enduml
diff --git a/doc/diagrams/useCases.puml b/doc/diagrams/useCases.puml
index 022bd4c..8d4aa71 100644
--- a/doc/diagrams/useCases.puml
+++ b/doc/diagrams/useCases.puml
@@ -9,12 +9,10 @@ actor "Human User" as user
 usecase "Play a match" as play
 usecase "Use as backend for machine player" as backend
 usecase "Generate a move" as genMove
-usecase "Train a neural network" as train
 
 player --> play
 gui --> backend
 user --> genMove
 gui --> genMove
-user --> train
 
 @enduml
diff --git a/doc/tex/biber.bib b/doc/tex/biber.bib
index 7dd5251..055ca8f 100644
--- a/doc/tex/biber.bib
+++ b/doc/tex/biber.bib
@@ -72,3 +72,9 @@
 	urldate      = {2021},
 	url          = {https://coverage.readthedocs.io}
 }
+
+@online{matplotlib_heatmaps,
+	title        = {Creating annotated heatmaps — Matplotlib 3.5.2 documentation},
+	urldate      = {2022},
+	url          = {https://matplotlib.org/stable/gallery/images_contours_and_fields/image_annotated_heatmap.html}
+}
diff --git a/doc/tex/previousWorks.tex b/doc/tex/previousWorks.tex
index bff0c82..6e503a3 100644
--- a/doc/tex/previousWorks.tex
+++ b/doc/tex/previousWorks.tex
@@ -1,17 +1,17 @@
 \section{Previous works}
 
-%\subsection{SGF}
-%
-%SGF (\textit{Smart Go Format} or, in a more general context, \textit{Smart Game
-%Format}) is a text file format specification for records of games or collections
-%of them. It was devised for Go but it supports other games with similar
-%turn-based structure. It supports move variations, annotations, setups and game
-%metadata. By supporting SGF our application can be used to analyse existing
-%games registered by other applications, such as those played on online Go
-%servers.
-%
-%The SGF specification can be found at
-%\url{https://www.red-bean.com/sgf/user_guide/index.html}
+\subsection{SGF}
+
+SGF (\textit{Smart Go Format} or, in a more general context, \textit{Smart Game
+Format}) is a text file format specification for records of games or collections
+of them. It was devised for Go but it supports other games with similar
+turn-based structure. It supports move variations, annotations, setups and game
+metadata. By supporting SGF our application can be used to analyse existing
+games registered by other applications, such as those played on online Go
+servers.
+
+The SGF specification can be found at
+\url{https://www.red-bean.com/sgf/user_guide/index.html}
 
 \subsection{GTP}
 
diff --git a/doc/tex/systemAnalysis.tex b/doc/tex/systemAnalysis.tex
index 044f2ee..e4962d3 100644
--- a/doc/tex/systemAnalysis.tex
+++ b/doc/tex/systemAnalysis.tex
@@ -249,51 +249,6 @@ requisites needed for the system.
 
 \setlist[enumerate,1]{label=\arabic*.}
 
-\subsection{System Actors}
-
-There are various actors who will interact with the system, both human and
-non-human.
-
-\begin{itemize}
-
-	\item The human player who interacts with the playing interface.
-	\item The human user who interacts with the engine.
-	\item A GUI software which uses the engine to generate moves.
-
-\end{itemize}
-
-\subsection{Use Cases}
-
-\begin{figure}[h]
-	\begin{center}
-		\includegraphics[width=\textwidth]{diagrams/useCases.png}
-		\caption{Use cases.}\label{fig:useCases}
-	\end{center}
-\end{figure}
-
-The different actors and use cases are represented on \fref{fig:useCases}. Each
-use case is explained next.
-
-\paragraph{Play a match}
-
-The game interface reads the moves presented by the player and shows their
-result on the board.
-
-\paragraph{Generate moves}
-
-The engine interface reads the input for generating a move as stated by the
-GTP protocol and outputs the coordinates of the board to play.
-
-\paragraph{Use as backend for machine player}
-
-The engine is used as the backend for generating moves for a machine player,
-this is, for automated play, either against a human who is using the GUI or
-against another machine player.
-
-\paragraph{Train a neural network}
-
-A neural network is trained by providing records of games.
-
 \subsection{Subsystems}
 
 There will be three main subsystems.
@@ -510,6 +465,8 @@ The classes resulting from the analysis phase are shown in
 	\bottomrule
 \end{tabular}
 
+\vspace{\interclassSpace}
+
 \begin{tabular}{p{\linewidth}}
 	\toprule
 	\textbf{NeuralNetwork} \\
@@ -542,6 +499,8 @@ The classes resulting from the analysis phase are shown in
 	\bottomrule
 \end{tabular}
 
+\vspace{\interclassSpace}
+
 \paragraph{Game System}
 
 \indent \\
@@ -585,7 +544,7 @@ The classes resulting from the analysis phase are shown in
 	\tabitem{Logic related to a board position.} \\
 	\midrule
 	\textbf{Proposed attributes} \\
-	\tabitem{\textbf{Player[][] board}: An array of the stones on the board.} \\
+	\tabitem{\textbf{board}: An array of the stones on the board.} \\
 	\midrule
 	\textbf{Proposed methods} \\
 	\tabitem{\textbf{getGroupLiberties()}: Returns a set with the empty vertices
@@ -644,6 +603,40 @@ The classes resulting from the analysis phase are shown in
 
 \vspace{\interclassSpace}
 
+\begin{tabular}{p{\linewidth}}
+	\toprule
+	\textbf{GameBoard} \\
+	\midrule
+	\textbf{Description} \\
+	Represents a board. Contains played stones and the amount of captures made
+	by each player. \\
+	\midrule
+	\textbf{Responsibilities} \\
+	\tabitem{Store a specific layout of stones in the board.} \\
+	\midrule
+	\textbf{Proposed attributes} \\
+	\tabitem{\textbf{board}: An array containing the stone layout.} \\
+	\tabitem{\textbf{capturesBlack}: The stones captured by black before the
+	position.} \\
+	\tabitem{\textbf{capturesWhite}: The stones captured by white before the
+	position.} \\
+	\midrule
+	\textbf{Proposed methods} \\
+	\tabitem{\textbf{getBoardHeight()}: Returns the number of rows of the board.} \\
+	\tabitem{\textbf{getBoardWidth()}: Returns the number of columns of the board.} \\
+	\tabitem{\textbf{getGroupLiberties()}: Returns a list with the empty
+	vertices adjacent to the group occupying a vertex.} \\
+	\tabitem{\textbf{getGroupVertices()}: Returns a list with the vertices
+	occupied by the group occupying a vertex.} \\
+	\tabitem{\textbf{moveAndCapture()}: Makes a move and captures the
+	corresponding stones if the move results in the capture of a group.} \\
+	\tabitem{\textbf{score()}: Gets the current score based on the already
+	surrounded territory. This follows Japanese rules.} \\
+	\bottomrule
+\end{tabular}
+
+\vspace{\interclassSpace}
+
 %TODO: Finish the classes of the Game System
 
 \paragraph{Training System}
@@ -655,46 +648,162 @@ The classes resulting from the analysis phase are shown in
 	\textbf{Trainer} \\
 	\midrule
 	\textbf{Description} \\
-	. \\
+	Provides the neural networks with moves to train on. \\
+	\midrule
+	\textbf{Responsibilities} \\
+	\tabitem{Obtain moves from stored records of matches.} \\
+	\tabitem{Provide neural networks with moves to train on.} \\
+	\midrule
+	\textbf{Proposed attributes} \\
+	%TODO: Explain why this is empty
+	\midrule
+	\textbf{Proposed methods} \\
+	%TODO: Explain why this is empty
+	\bottomrule
+\end{tabular}
+
+\vspace{\interclassSpace}
+
+\begin{tabular}{p{\linewidth}}
+	\toprule
+	\textbf{Parser} \\
+	\midrule
+	\textbf{Description} \\
+	Reads SGF files and converts them to a tree of GameMove from the Game
+	System. \\
+	\midrule
+	\textbf{Responsibilities} \\
+	\tabitem{Read SGF files.} \\
+	\tabitem{Convert the content of the SGF files to a tree of GameMove.} \\
+	\midrule
+	\textbf{Proposed attributes} \\
+	%TODO: Explain why this is empty
+	\midrule
+	\textbf{Proposed methods} \\
+	%TODO: Explain why this is empty
+	\bottomrule
+\end{tabular}
+
+\vspace{\interclassSpace}
+
+\begin{tabular}{p{\linewidth}}
+	\toprule
+	\textbf{ASTNode} \\
+	\midrule
+	\textbf{Description} \\
+	Makes up the tree resulting from the parsing of an SGF file.\\
 	\midrule
 	\textbf{Responsibilities} \\
-	\tabitem{.} \\
+	\tabitem{Obtain a GameMove tree from itself and its children.} \\
 	\midrule
 	\textbf{Proposed attributes} \\
-	\tabitem{\textbf{}: .} \\
+	\tabitem{\textbf{children}: The nodes following from itself.} \\
+	\tabitem{\textbf{props}: The properties of the tree read from an SGF file.}
+	\\
 	\midrule
 	\textbf{Proposed methods} \\
-	\tabitem{\textbf{}: .} \\
+	\tabitem{\textbf{toGameTree()}: Returns a GameMove tree corresponding to the
+	tree following from this node.} \\
 	\bottomrule
 \end{tabular}
 
+\vspace{\interclassSpace}
+
+\subsection{System Actors}
+
+There are various actors who will interact with the system, both human and
+non-human.
+
+\begin{itemize}
+
+	\item The human player who interacts with the playing interface.
+	\item The human user who interacts with the engine.
+	\item A GUI software which uses the engine to generate moves.
+
+\end{itemize}
+
+\subsection{Use Cases}
+
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/useCases.png}
+		\caption{Use cases.}
+		\label{fig:useCases}
+	\end{center}
+\end{figure}
+
+The different actors and use cases are represented on \fref{fig:useCases}. Each
+use case is explained next.
+
+\paragraph{Play a match}
+
+The game interface reads the moves presented by the player and shows their
+result on the board.
+
+\paragraph{Use as backend for machine player}
+
+The engine is used as the backend for generating moves for a machine player,
+this is, for automated play, either against a human who is using the GUI or
+against another machine player.
+
+\paragraph{Generate a move}
+
+The engine interface reads the input for generating a move as stated by the
+GTP protocol and outputs the coordinates of the board to play.
+
 \subsection{Use case analysis and scenarios}
 
-\indent
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/useCase_playAMatch.png}
+		\caption{Use case: Play a match.}
+		\label{fig:useCase_playAMatch}
+	\end{center}
+\end{figure}
 
 \begin{tabular}{lp{0.7\linewidth}}
 	\toprule
-	\multicolumn{2}{c}{\textbf{Play a match (Make a move?)}} \\
+	\multicolumn{2}{c}{\textbf{Play a match}} \\
 	\midrule
 	\textbf{Preconditions} & The game interface has been started. \\
 	\midrule
-	\textbf{Postconditions} & Description of postconditions \\
+	\textbf{Postconditions} & The program terminates after a match has been
+	played. \\
 	\midrule
-	\textbf{Actors} & Actors \\
+	\textbf{Actors} & Human player \\
 	\midrule
-	\textbf{Description} & Description \\
+	\textbf{Description} &
+		1. The user enters the move to make.\newline
+		2. The result of playing that move is outputted by the program.\newline
+		3. Stop the program if the game has ended or go back to 1 if not. \\
 	\midrule
-	\textbf{Secondary scenarios} & Secondary scenarios \\
+	\textbf{Secondary scenarios} &
+	\textbf{The move is illegal}: An error message is shown. Go back to step 1 of
+	main scenario. \\
 	\midrule
-	\textbf{Exceptions} & Exceptions \\
+	\textbf{Exceptions} &
+	\textbf{The input is wrong}: An error message is shown. Go back to step 1 of
+	main scenario. \\
 	\midrule
 	\textbf{Notes} &
-	---\\
+	This scenario does not pretend to be a complete recreation of a go match. It
+	will be playable, but its main purpose is to see the Game implementation in
+	action.\newline
+	A robustness diagram for this scenario is shown in
+	\fref{fig:useCase_playAMatch}.\\
 	\bottomrule
 \end{tabular}
 
 \vspace{\interclassSpace}
 
+\begin{figure}[h]
+	\begin{center}
+		\includegraphics[width=\textwidth]{diagrams/useCase_generateAMove.png}
+		\caption{Use case: Generate a move.}
+		\label{fig:useCase_generateAMove}
+	\end{center}
+\end{figure}
+
 \begin{tabular}{lp{0.7\linewidth}}
 	\toprule
 	\multicolumn{2}{c}{\textbf{Generate a move}} \\
@@ -719,21 +828,21 @@ The classes resulting from the analysis phase are shown in
 	\midrule
 	\textbf{Exceptions} &
 	\textbf{The input is wrong}: An error message is shown. Go back to step 1 of
-	main scenario.\\
+	main scenario. \\
 	\midrule
 	\textbf{Notes} &
-	---\\
+	A robustness diagram for this scenario is shown in
+	\fref{fig:useCase_generateAMove}.\\
 	\bottomrule
 \end{tabular}
 
 \vspace{\interclassSpace}
 
-\subsubsection{Use as backend for machine player}
-
 \begin{figure}[h]
 	\begin{center}
 		\includegraphics[width=\textwidth]{diagrams/useCase_useAsBackend.png}
-		\caption{Use as backend for machine player}
+		\caption{Use case: Use as backend for machine player.}
+		\label{fig:useCase_useAsBackend}
 	\end{center}
 \end{figure}
 
@@ -749,10 +858,13 @@ The classes resulting from the analysis phase are shown in
 	\textbf{Actors} & GUI program. \\
 	\midrule
 	\textbf{Description} &
-		1. The program gives commands to the engine. The specific commands will
-		vary from program to program.\newline
-		2. The engine suggest moves to the program.\newline
-		3. The moves are shown by the program as if made by another player.\\
+		1. The program gives commands to the engine to set up the game. The
+		specific commands will vary from program to program.\newline
+		2. The program asks the engine for a move.\newline
+		3. The engine suggest a move to the program.\newline
+		4. The moves are shown by the program as if made by a player.\newline
+		5. The opponent gives a move to the program.\newline
+		6. Repeat from step 2 until the game ends. \\
 	\midrule
 	\textbf{Secondary scenarios} &
 	---\\
@@ -761,10 +873,13 @@ The classes resulting from the analysis phase are shown in
 	---\\
 	\midrule
 	\textbf{Notes} &
-	---\\
+	A robustness diagram for this scenario is shown in
+	\fref{fig:useCase_useAsBackend}.\\
 	\bottomrule
 \end{tabular}
 
+\vspace{\interclassSpace}
+
 \subsection{Testing Plan Specification}
 
 \subsubsection{Unitary Testing}