Classes that are generally fully complete have been documented

core/src/uk/ac/york/student/GdxGame.java

@@ -16,83 +16,146 @@
 
 import static com.badlogic.gdx.scenes.scene2d.actions.Actions.fadeOut;
 
+/**
+ * This is the main game class for the application. It extends the {@link Game} class from the libGDX library.
+ * The {@link Game} class is the base class for all games, handling the lifecycle of the application and the transition between screens.
+ * This class is declared as final, meaning it cannot be subclassed.
+ */
 public final class GdxGame extends Game {
 
+	/**
+	 * Default constructor for the {@link GdxGame} class.
+	 * Calls the superclass constructor.
+	 */
 	public GdxGame() {
 		super();
 	}
-
+
+	/**
+	 * This method is called when the application is created.
+	 * It initializes the {@link MusicManager} and {@link SoundManager} and sets the initial screen to {@link Screens#LOADING}
+	 */
 	@Override
 	public void create() {
+		// Get the instance of the music manager and enable it
 		final AudioManager musicManager = MusicManager.getInstance();
 		musicManager.onEnable();
 
+		// Get the instance of the sound manager and enable it
 		final AudioManager soundManager = SoundManager.getInstance();
 		soundManager.onEnable();
 
+		// Set the initial screen to the loading screen
 		setScreen(Screens.LOADING);
 	}
 
 	/**
-	 * Set the current screen
-	 * @param screen - the screen to set (use Screens class)
+	 * Sets the current screen to the specified screen class.
+	 * The current screen, retrieved from {@link GdxGame#getScreen()}, is disposed using {@link BaseScreen#dispose()} before the new screen is set.
+	 * The new screen is instantiated using reflection, with the constructor that takes a single argument of type {@link GdxGame}.
+	 * If an error occurs during the instantiation of the new screen, an error is logged and the application is exited.
+	 *
+	 * @param screen The class of the screen to set. This class must extend {@link BaseScreen} and have a constructor that takes a single argument of type {@link GdxGame}.
 	 */
 	public void setScreen(@NotNull Class<? extends BaseScreen> screen) {
-		// dispose current screen
+		// Dispose the current screen if it exists
 		final Screen currentScreen = getScreen();
 		if (currentScreen != null) {
 			currentScreen.dispose();
 		}
 
-        BaseScreen newScreen;
+		// Create a new screen instance
+		BaseScreen newScreen;
 		try {
-            newScreen = screen.getConstructor(GdxGame.class).newInstance(this);
-        } catch (InstantiationException | IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
-            Gdx.app.error("LetRonCooke", "Error loading screen", e);
+			// Instantiate the new screen using reflection
+			newScreen = screen.getConstructor(GdxGame.class).newInstance(this);
+		} catch (InstantiationException | IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
+			// Log the error and exit the application if the new screen cannot be instantiated
+			Gdx.app.error("LetRonCooke", "Error loading screen", e);
 			Gdx.app.exit();
 			return;
-        }
-        super.setScreen(newScreen);
+		}
+
+		// Set the new screen
+		super.setScreen(newScreen);
 	}
 
+	/**
+	 * Sets the current screen to the specified screen class with an option to fade in.
+	 * The current screen, retrieved from {@link GdxGame#getScreen()}, is disposed using {@link BaseScreen#dispose()} before the new screen is set.
+	 * The new screen is instantiated using reflection, with the constructor that takes a single argument of type {@link GdxGame} and a boolean indicating whether the screen should fade in.
+	 * If an error occurs during the instantiation of the new screen, an error is logged and the application is exited.
+	 *
+	 * @param screen The class of the screen to set. This class must extend {@link BaseScreen} and have a constructor that takes a single argument of type {@link GdxGame} and a boolean.
+	 * @param shouldFadeIn A boolean indicating whether the new screen should fade in.
+	 */
 	public void setScreen(@NotNull Class<? extends BaseScreen> screen, boolean shouldFadeIn) {
-		// dispose current screen
+		// Dispose the current screen if it exists
 		final Screen currentScreen = getScreen();
 		if (currentScreen != null) {
 			currentScreen.dispose();
 		}
 
+		// Create a new screen instance
 		BaseScreen newScreen;
 		try {
+			// Instantiate the new screen using reflection
 			newScreen = screen.getConstructor(GdxGame.class, boolean.class).newInstance(this, shouldFadeIn);
 		} catch (InstantiationException | IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
+			// Log the error and exit the application if the new screen cannot be instantiated
 			Gdx.app.error("LetRonCooke", "Error loading screen", e);
 			Gdx.app.exit();
 			return;
 		}
+
+		// Set the new screen
 		super.setScreen(newScreen);
 	}
 
+	/**
+	 * Sets the current screen to the specified screen class with an option to fade in and a specified fade-in time.
+	 * The current screen, retrieved from {@link GdxGame#getScreen()}, is disposed using {@link BaseScreen#dispose()} before the new screen is set.
+	 * The new screen is instantiated using reflection, with the constructor that takes a single argument of type {@link GdxGame}, a boolean indicating whether the screen should fade in, and a float specifying the fade-in time.
+	 * If an error occurs during the instantiation of the new screen, an error is logged and the application is exited.
+	 *
+	 * @param screen The class of the screen to set. This class must extend {@link BaseScreen} and have a constructor that takes a single argument of type {@link GdxGame}, a boolean, and a float.
+	 * @param shouldFadeIn A boolean indicating whether the new screen should fade in.
+	 * @param fadeInTime A float specifying the time for the fade-in effect in seconds
+	 */
 	public void setScreen(@NotNull Class<? extends BaseScreen> screen, boolean shouldFadeIn, float fadeInTime) {
-		// dispose current screen
+		// Dispose the current screen if it exists
 		final Screen currentScreen = getScreen();
 		if (currentScreen != null) {
 			currentScreen.dispose();
 		}
 
+		// Create a new screen instance
 		BaseScreen newScreen;
 		try {
+			// Instantiate the new screen using reflection
 			newScreen = screen.getConstructor(GdxGame.class, boolean.class, float.class).newInstance(this, shouldFadeIn, fadeInTime);
 		} catch (InstantiationException | IllegalAccessException | InvocationTargetException | NoSuchMethodException e) {
+			// Log the error and exit the application if the new screen cannot be instantiated
 			Gdx.app.error("LetRonCooke", "Error loading screen", e);
 			Gdx.app.exit();
 			return;
 		}
+
+		// Set the new screen
 		super.setScreen(newScreen);
 	}
 
+	/**
+	 * Transitions to a new screen with a fade-out effect.
+	 * The current screen, retrieved from {@link GdxGame#getScreen()}, is checked if it's an instance of {@link BaseScreen}.
+	 * If the current screen is null or not an instance of {@link BaseScreen}, the new screen is set immediately without transition.
+	 * If the current screen is an instance of {@link BaseScreen}, a fade-out effect is applied to the current screen before transitioning to the new screen.
+	 * The new screen is set with a fade-in effect.
+	 *
+	 * @param screen The class of the screen to transition to. This class must extend {@link BaseScreen} and have a constructor that takes a single argument of type {@link GdxGame}.
+	 */
 	public void transitionScreen(@NotNull Class<? extends BaseScreen> screen) {
-		// dispose current screen
+		// Dispose current screen
 		final Screen currentScreen = getScreen();
 		if (currentScreen == null) {
 			setScreen(screen);
@@ -106,24 +169,40 @@ public void transitionScreen(@NotNull Class<? extends BaseScreen> screen) {
 
 		final BaseScreen baseScreen = (BaseScreen) currentScreen;
 
+		// Set the alpha value of the root's color to 1
 		baseScreen.getProcessor().getRoot().getColor().a = 1;
 		SequenceAction sequenceAction = new SequenceAction();
+		// Add a fade-out action to the sequence
 		sequenceAction.addAction(Actions.fadeOut(0.5f));
+		// Add a run action to the sequence that sets the new screen with a fade-in effect
 		sequenceAction.addAction(Actions.run(() -> setScreen(screen, true, 0.5f)));
+		// Add the sequence action to the root
 		baseScreen.getProcessor().getRoot().addAction(sequenceAction);
 	}
 
 
+	/**
+	 * Renders the game, updating the screen display.
+	 * This method is called by the game loop from the application every time rendering should be performed.
+	 * This method calls the render method of the superclass {@link Game}, which in turn calls the render method of the current screen.
+	 */
 	@Override
 	public void render() {
 		super.render();
 	}
-
+
+	/**
+	 * Disposes the game, cleaning up resources.
+	 * This method is called when the application is about to be closed.
+	 * It retrieves the instances of {@link MusicManager} and {@link SoundManager} and disables them, stopping all audio playback and releasing audio resources.
+	 */
 	@Override
 	public void dispose() {
+		// Get the instance of the music manager and disable it
 		final AudioManager musicManager = MusicManager.getInstance();
 		musicManager.onDisable();
 
+		// Get the instance of the sound manager and disable it
 		final AudioManager soundManager = SoundManager.getInstance();
 		soundManager.onDisable();
 	}

core/src/uk/ac/york/student/player/PlayerEnergy.java

@@ -3,55 +3,95 @@
 import com.badlogic.gdx.scenes.scene2d.ui.ProgressBar;
 import org.jetbrains.annotations.Range;
 
+/**
+ * The PlayerEnergy class represents the energy level of a player in the game.
+ * It implements the PlayerMetric interface, indicating that it is a type of metric used for the player.
+ * The energy level is represented as a float value between 0 and 1, where 0 is no energy and 1 is full energy.
+ * The class also includes a ProgressBar to visually represent the energy level.
+ */
 public class PlayerEnergy implements PlayerMetric {
+    /**
+     * The ProgressBar instance for the PlayerEnergy class.
+     * This ProgressBar represents the energy level of the player in the game.
+     * The minimum value is 0 (no energy), the maximum value is 1 (full energy), and the step size is 0.1.
+     * The ProgressBar does not have a vertical orientation (false), and uses the Craftacular skin from {@link PlayerMetric#skin}.
+     */
     private final ProgressBar progressBar = new ProgressBar(0, 1, 0.1f, false, skin);
 
+    /**
+     * Constructor for the PlayerEnergy class.
+     * This constructor initializes the ProgressBar that represents the player's energy level.
+     */
     public PlayerEnergy() {
-        progressBar.setWidth(200);
-        progressBar.setHeight(50);
-        progressBar.setAnimateDuration(0.25f);
+        progressBar.setWidth(200); // Set the width of the ProgressBar to 200
+        progressBar.setHeight(50); // Set the height of the ProgressBar to 50
+        progressBar.setAnimateDuration(0.25f); // Set the animation duration of the ProgressBar to 0.25 seconds
     }
 
+    /**
+     * The energy level of the player.
+     * This is a float value between 0 and 1, where 0 represents no energy and 1 represents full energy.
+     * By default, the energy level is set to 1 (full energy).
+     */
     private @Range(from=0, to=1) float energy = 1f;
     /**
-     * Get the hunger of the player as a float between 0 and 1
-     * Where 0 is not hungry and 1 is very hungry
-     * @return the hunger of the player
+     * Get the energy level of the player.
+     * This is a float value between 0 and 1, where 0 represents no energy and 1 represents full energy.
+     * @return the energy level of the player
      */
     @Range(from=0, to=1) float getEnergy() {
         return energy;
     }
 
     /**
-     * Set the hunger of the player
-     * @param energy the hunger of the player as a float between 0 and 1
+     * Set the energy level of the player.
+     * This method takes a float value between 0 and 1 as an argument, where 0 represents no energy and 1 represents full energy.
+     * The energy level is then set to the maximum of the minimum energy level ({@link PlayerMetric#PROGRESS_BAR_MINIMUM}) and the minimum of 1 and the provided energy level.
+     * This ensures that the energy level is always within the valid range.
+     * @param energy the new energy level of the player
      */
     void setEnergy(@Range(from=0, to=1) float energy) {
         this.energy = Math.max(PROGRESS_BAR_MINIMUM, Math.min(1, energy));
     }
 
     /**
-     * Increase the hunger of the player by a given amount
-     * @param amount the amount to increase the hunger by
+     * Increase the energy level of the player.
+     * This method takes a float value as an argument, which represents the amount of energy to be added to the player's current energy level.
+     * The new energy level is then set to the minimum of 1 and the sum of the current energy level and the provided amount.
+     * This ensures that the energy level does not exceed 1 (full energy).
+     * @param amount the amount of energy to be added to the player's current energy level
      */
     void increaseEnergy(float amount) {
         energy = Math.min(1, energy + amount);
     }
 
     /**
-     * Decrease the hunger of the player by a given amount
-     * @param amount the amount to decrease the hunger by
+     * Decrease the energy level of the player.
+     * This method takes a float value as an argument, which represents the amount of energy to be subtracted from the player's current energy level.
+     * The new energy level is then set to the maximum of the minimum energy level ({@link PlayerMetric#PROGRESS_BAR_MINIMUM}) and the difference between the current energy level and the provided amount.
+     * This ensures that the energy level does not go below the minimum energy level.
+     * @param amount the amount of energy to be subtracted from the player's current energy level
      */
     void decreaseEnergy(float amount) {
         energy = Math.max(PROGRESS_BAR_MINIMUM, energy - amount);
     }
 
+    /**
+     * Get the ProgressBar representing the player's energy level.
+     * This method first sets the value of the ProgressBar to the current energy level of the player.
+     * It then returns the ProgressBar.
+     * @return the ProgressBar representing the player's energy level
+     */
     @Override
     public ProgressBar getProgressBar() {
         progressBar.setValue(getEnergy());
         return progressBar;
     }
 
+    /**
+     * Get the label used to display on the screen for the player's energy level.
+     * @return the label for the player's energy level
+     */
     @Override
     public String getLabel() {
         return "Energy";