From 0a73db0e47a93dcf70be2ed75cd64e1762ae316c Mon Sep 17 00:00:00 2001
From: pacien
Date: Sun, 14 Jan 2018 23:08:42 +0100
Subject: Elaborate dev report

Signed-off-by: pacien <pacien.trangirard@pacien.net>
---
 src/docs/dev.md | 87 +++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 66 insertions(+), 21 deletions(-)

(limited to 'src')

diff --git a/src/docs/dev.md b/src/docs/dev.md
index 2f3e3b5..5267bb7 100644
--- a/src/docs/dev.md
+++ b/src/docs/dev.md
@@ -1,7 +1,7 @@
 ---
 title: "BSc IN S5 / OOP with Java / Wall-J / Wall-J / Devel. notes"
 author: [Pacien TRAN-GIRARD, Adam NAILI]
-date: 2018-01-03
+date: 2018-01-14
 ...
 
 # Preamble
@@ -10,7 +10,8 @@ date: 2018-01-03
 worlds.
 
 Being part of the "OOP with Java" course at [UPEM](http://www.u-pem.fr/), this application has been entirely
-written in Java and makes use of the Zen5 and [JBox2D](http://www.jbox2d.org/) libraries.
+written in Java and makes use of the Zen5, [JBox2D](http://www.jbox2d.org/) and
+[JUnit5](http://junit.org/junit5/) libraries.
 
 ## Licensing
 
@@ -26,45 +27,89 @@ Build-time and embedded run-time dependencies of this program are licensed under
 
 ## Building the project
 
-TODO:
+Compilation and production of the different output files is done through Ant and requires a JDK $\geq$ 8.
+All the required dependencies of the program are shipped with the project archive,
+as the use of Maven was not permitted.
+
+Available Ant targets are:
+
+- `compile`: compiles the Java sources
+- `jar`: generates an autonomous executable Java Archive
+- `javadoc`: generates the API documentation
+- `clean`: deletes the generated resources
+- `docs`: compiles the PDF reports (requires Pandoc and PlantUML)
+- `zip`: generates the project archive file
 
-- compilation done through ant
-- needs jdk >= 8
-- dependencies included in the jar
+Unit tests can be executed through JUnitStarter, the JUnit Ant plugin not supporting JUnit 5.
 
 ## Running the program
 
-See the user manual.
+_Refer to the user manual (user.pdf)._
 
----
+\newpage
 
-# Implementation details
+# Considerations
 
-## Considerations
+## Specification refinement
 
-### Specification refinement
+The initial specifications have been refined, defining unspecified and implied constraints.
 
-TODO:
+A _board_ or _world_ has been defined as a grid of blocks of the same size.
+Their respective properties such as their traversability by the player have been detailed in the user manual.
+
+Additional constraints on board validity have been added to ensure their correctness during their manipulation in the
+program. Those conditions have been described in the user manual as well.
+
+## Unit testing
+
+_"Sir, the testing?"_, Caroline reminds.
+Most utility, logic functions and algorithms have been covered by automatic unit tests to reduce the risk of
+small-but-yet-critical mistakes and regressions during the development.
+Those automatic tests are ran with the help of the JUnit 5 test framework.
+
+Components and modules related to the graphical user interface could not have been easily tested automatically.
+Quality control of such parts of the program have been handled manually.
+
+## Architecture
 
-- specs not clear in every possible way
-- refined as such: world is made of tiles some of which defined traversable, defined coniditons of validity of a map
-- see user manual
+The architecture of the program is loosely based on the _Model-View-Controller_ pattern, combined with an event-driven
+approach, separating state objects from actions and events handlers.
 
-### Unit testing
+A more complete package and class diagram is attached to this report.
 
 TODO:
 
-- tests are necessary
-- junit5, no ant plugin for this version, runs through the IDE
+- include a simplified diagram here
+- explain event handling and propagation
+- explain how it minimizes coupling
+- explain how we can add stuff like a second robot and whatnot
 
-## Modules
+## Implementation details
 
 TODO:
 
-- class diagram
-- package and class roles outline
+- per-module remarks:
+    - tell who did what in parallel
+    - using a ray tracer for explosions
 
 ## Additional features
 
+None yet.
+
 ## Notes
 
+TODO:
+
+- complain about Ant, beg for Gradle and dependency management
+- check that zen5 is actually using a double buffer
+- include git commit log?
+
+---
+
+# References
+
+TODO:
+
+- jbox2d, zen5, jdk, ant, junit docs
+- A* on wikipedia
+- common sense
-- 
cgit v1.2.3