add docs and tests

src/main/java/org/ois/core/project/SimulationManifest.java

@@ -25,7 +25,6 @@ public class SimulationManifest implements DataObject<SimulationManifest> {
      * This map must contain at least one entry.
      */
     private Map<String, String> states = new Hashtable<>();
-
     /** The set of supported platforms for the simulation, based on {@link RunnerConfiguration.RunnerType}. */
     private Set<RunnerConfiguration.RunnerType> platforms = new HashSet<>();
     /** The width of the screen the simulation needs, in pixels. */
@@ -78,6 +77,30 @@ public DataNode convertToDataNode() {
         return root;
     }
 
+    // Setters and Getters
+
+    /**
+     * Sets the initial state of the project.
+     *
+     * @param initialState the initial state of the project.
+     * @return this {@link SimulationManifest} object.
+     */
+    public SimulationManifest setInitialState(String initialState) {
+        this.initialState = initialState;
+        return this;
+    }
+
+    /**
+     * Sets the states of the simulation.
+     *
+     * @param states A map of state keys to the class name of the corresponding `IState` implementation.
+     * @return this {@link SimulationManifest} object.
+     */
+    public SimulationManifest setStates(Map<String, String> states) {
+        this.states = states;
+        return this;
+    }
+
     /**
      * Sets the project title.
      *

src/main/java/org/ois/core/runner/RunnerConfiguration.java

@@ -10,16 +10,26 @@
 
 /**
  * The Unified Configuration to be used in the Simulation Engine.
- * Passing the specific runner (platform) variables in a unified way
+ * This class provides a way to set and retrieve configuration parameters for
+ * running simulations across different platforms.
  */
 @SuppressWarnings("unused")
 public class RunnerConfiguration {
 
-    // The Supported application running platforms by the runners
+    /**
+     * Enum representing the supported application running platforms by the runners.
+     */
     public enum RunnerType {
         Desktop, Html, Android
     }
 
+    /**
+     * Converts a string representation of a platform to a {@link RunnerType}.
+     *
+     * @param platform The string representation of the platform (e.g., "html", "android", "desktop").
+     * @return The corresponding {@link RunnerType}.
+     * @throws RuntimeException if the platform is not supported.
+     */
     public static RunnerType toPlatform(String platform) {
         switch (platform.trim().toLowerCase()) {
             case "html": return RunnerType.Html;
@@ -32,43 +42,91 @@ public static RunnerType toPlatform(String platform) {
     private ILogger.Level logLevel;
     private String[] logTopics;
     private RunnerType type;
-
     private SimulationManifest simulationManifest;
 
+    /**
+     * Sets the type of the runner configuration.
+     *
+     * @param type The runner type to set.
+     * @return The current instance of {@link RunnerConfiguration} for method chaining.
+     */
     public RunnerConfiguration setType(RunnerType type) {
         this.type = type;
         return this;
     }
 
+    /**
+     * Sets the simulation manifest for this runner configuration.
+     *
+     * @param manifest The simulation manifest to set.
+     * @return The current instance of {@link RunnerConfiguration} for method chaining.
+     */
     public RunnerConfiguration setSimulationManifest(SimulationManifest manifest) {
         this.simulationManifest = manifest;
         return this;
     }
 
+    /**
+     * Sets the log topics for this runner configuration.
+     *
+     * @param logTopics An array of log topics to set.
+     */
     public void setLogTopics(String[] logTopics) {
         this.logTopics = logTopics;
     }
 
+    /**
+     * Sets the log level for this runner configuration.
+     *
+     * @param logLevel The log level to set.
+     */
     public void setLogLevel(ILogger.Level logLevel) {
         this.logLevel = logLevel;
     }
 
+    /**
+     * Retrieves the log topics set for this runner configuration.
+     *
+     * @return An array of log topics.
+     */
     public String[] getLogTopics() {
         return logTopics;
     }
 
+    /**
+     * Retrieves the log level set for this runner configuration.
+     *
+     * @return The log level.
+     */
     public ILogger.Level getLogLevel() {
         return logLevel;
     }
 
+    /**
+     * Retrieves the runner type set for this configuration.
+     *
+     * @return The runner type.
+     */
     public RunnerType getType() {
         return this.type;
     }
 
+    /**
+     * Retrieves the simulation manifest associated with this runner configuration.
+     *
+     * @return The simulation manifest.
+     */
     public SimulationManifest getSimulationManifest() {
         return this.simulationManifest;
     }
 
+    /**
+     * Creates a {@link RunnerConfiguration} instance from a simulation configuration file stream.
+     *
+     * @param simulationConfigFileStream The input stream of the simulation configuration file.
+     * @return A {@link RunnerConfiguration} instance populated with data from the configuration file.
+     * @throws IOException if an error occurs while reading the configuration file.
+     */
     public static RunnerConfiguration getRunnerConfigurations(InputStream simulationConfigFileStream) throws IOException {
         return new RunnerConfiguration().setSimulationManifest(JsonFormat.compact().load(new SimulationManifest(), simulationConfigFileStream));
     }

src/main/java/org/ois/core/runner/SimulationEngine.java

@@ -20,24 +20,39 @@
 import java.lang.reflect.InvocationTargetException;
 import java.util.Map;
 
+/**
+ * The main simulation engine for the OIS project.
+ * This class manages the application's lifecycle, including loading and managing
+ * the states of the simulation.
+ */
 public class SimulationEngine extends ApplicationAdapter {
     private static final Logger<SimulationEngine> log = Logger.get(SimulationEngine.class);
 
-    // The Gdx application
+    /** The Gdx application **/
     private Application app;
-    // The engine runner configuration with information from the dynamic project (Graphic, Meta-data...)
+    /** The engine runner configuration with information from the dynamic project (Graphic, Meta-data...) **/
     private final RunnerConfiguration configuration;
-
-    // The state manager that handles the states of the simulations provided by the project;
+    /** The state manager that handles the states of the simulations provided by the project; **/
     public final StateManager stateManager;
+    /** The Error state, if the stateManager throws an error, the engine will switch to this state **/
     public final ErrorState errorState;
 
+    /**
+     * Constructs a new SimulationEngine with the specified configuration.
+     *
+     * @param configuration The configuration to be used by the simulation engine.
+     */
     public SimulationEngine(RunnerConfiguration configuration) {
         this.configuration = configuration;
         this.stateManager = new StateManager();
         this.errorState = new ErrorState();
     }
 
+    /**
+     * Retrieves the runner configuration for this engine.
+     *
+     * @return The runner configuration.
+     */
     public RunnerConfiguration getRunnerConfig() {
         return this.configuration;
     }
@@ -59,7 +74,16 @@ public void create() {
         }
     }
 
-    private void loadProject() throws ReflectionException, InvocationTargetException, NoSuchMethodException, InstantiationException, IllegalAccessException {
+    /**
+     * Loads the project manifest if needed and initializes the project states using reflection from the manifest.
+     *
+     * @throws ReflectionException if there is an error during reflection.
+     * @throws InvocationTargetException if a method cannot be invoked.
+     * @throws NoSuchMethodException if the method to invoke cannot be found.
+     * @throws InstantiationException if an instance cannot be created.
+     * @throws IllegalAccessException if access to the method or constructor is denied.
+     */
+    public void loadProject() throws ReflectionException, InvocationTargetException, NoSuchMethodException, InstantiationException, IllegalAccessException {
        SimulationManifest manifest = configuration.getSimulationManifest();
        if (manifest == null) {
            // For HTML, at Launcher we don't have access to resources.
@@ -82,7 +106,13 @@ private void loadProject() throws ReflectionException, InvocationTargetException
         this.stateManager.start(manifest.getInitialState());
     }
 
+    /**
+     * Stops the application gracefully.
+     */
     public void stop() {
+        if (this.app == null) {
+            return;
+        }
         this.app.exit();
     }
 
@@ -147,19 +177,35 @@ public void dispose() {
         this.errorState.dispose();
     }
 
+    /**
+     * Retrieves the current application width in pixel.
+     *
+     * @return The width of the application.
+     */
     public int getAppWidth()
     {
         return Gdx.graphics.getWidth();
     }
 
+    /**
+     * Retrieves the current application height in pixel.
+     *
+     * @return The height of the application.
+     */
     public int getAppHeight()
     {
         return Gdx.graphics.getHeight();
     }
 
-    private void handleProgramException(Exception exception) {
+    /**
+     * Handles exceptions that occur during the execution of the program.
+     *
+     * @param exception The exception to handle.
+     */
+    public void handleProgramException(Exception exception) {
         if (errorState.isActive()) {
             stop();
+            return;
         }
         errorState.enter(exception);
     }

src/main/java/org/ois/core/state/ErrorState.java

@@ -3,13 +3,33 @@
 import com.badlogic.gdx.utils.ScreenUtils;
 import org.ois.core.utils.log.Logger;
 
+/**
+ * Represents the error state in the simulation.
+ * This state is activated when the state manager encounters an error,
+ * allowing the simulation to handle exceptions gracefully.
+ */
 public class ErrorState implements IState {
 
     private static final Logger<ErrorState> log = Logger.get(ErrorState.class);
 
 //    private final List<Exception> exceptions = new ArrayList<>();
+
+    /** Indicates whether the error state is currently active. **/
     private boolean isActive = false;
 
+    /**
+     * Checks if the error state is currently active.
+     *
+     * @return True if the error state is active, false otherwise.
+     */
+    public boolean isActive() {return isActive;}
+
+    /**
+     * Called when entering the error state.
+     * Logs any provided exceptions and sets the state to active.
+     *
+     * @param parameters Optional parameters, typically containing exceptions.
+     */
     @Override
     public void enter(Object... parameters) {
         for (Object param : parameters) {
@@ -22,42 +42,29 @@ public void enter(Object... parameters) {
     }
 
     @Override
-    public void exit() {
-        isActive = false;
-    }
-
-    public boolean isActive() {
-        return isActive;
-    }
+    public void exit() {isActive = false;}
 
     @Override
-    public void pause() {
-
+    public void render() {
+        ScreenUtils.clear(1,1,1, 1f);
     }
 
     @Override
-    public void resume() {
-
+    public boolean update(float dt) {
+        // TODO: any key will make the state exit
+        return true;
     }
 
     @Override
-    public void resize(int width, int height) {
-
-    }
+    public void resize(int width, int height) {}
 
     @Override
-    public void render() {
-        ScreenUtils.clear(1,1,1, 1f);
-    }
+    public void dispose() {isActive = false; }
 
     @Override
-    public boolean update(float dt) {
-        // TODO: any key will make the state exit
-        return true;
-    }
+    public void pause() {}
 
     @Override
-    public void dispose() {
+    public void resume() {}
 
-    }
 }