Update in-code documentation

audio/src/main/kotlin/cyberpunk/audio/MusicManager.kt

@@ -14,7 +14,6 @@ object MusicManager {
 
   /**
    * Creates and loads a [Music] object onto the [tracks] structure.
-   *
    * @param trackName key that will identify this track in the map.
    * @param path      track's path inside the assets folder.
    */
@@ -29,7 +28,6 @@ object MusicManager {
    * If no volume is specified (the second parameter), then the sound will be played with
    * the default volume, 1f.
    * Contrarily to the sound instances, this action doesn't return an unique id.
-   *
    * @param trackName key that identifies the track in the map.
    * @param volume    audio volume; ranges between [0, 1] and it's optional.
    * @throws AudioAssetNotFoundException
@@ -45,7 +43,6 @@ object MusicManager {
 
   /**
    * Pauses the given track's playback.
-   *
    * @param trackName key that identifies the track in the map.
    * @throws AudioAssetNotFoundException
    */
@@ -56,7 +53,6 @@ object MusicManager {
 
   /**
    * Stops the given track's playback.
-   *
    * @param trackName key that identifies the track in the map.
    * @throws AudioAssetNotFoundException
    */
@@ -67,7 +63,6 @@ object MusicManager {
 
   /**
    * Repeats the given track's playback until [stop] is called.
-   *
    * @param trackName key that identifies the track in the map.
    * @throws AudioAssetNotFoundException
    */
@@ -79,8 +74,7 @@ object MusicManager {
   }
 
   /**
-   * Whether or not the given track is playing.
-   *
+   * Checks whether or not the given track is playing.
    * @param trackName key that identifies the track in the map.
    * @return whether or not the given track is playing.
    * @throws AudioAssetNotFoundException
@@ -91,8 +85,7 @@ object MusicManager {
     tracks[trackName]?.isPlaying ?: throw AudioAssetNotFoundException("$trackName not found.")
 
   /**
-   * Whether or not the given track is looping.
-   *
+   * Checks whether or not the given track is looping.
    * @param trackName key that identifies the track in the map.
    * @return whether or not the given track is looping.
    * @throws AudioAssetNotFoundException
@@ -104,7 +97,6 @@ object MusicManager {
 
   /**
    * Gets this track's current position in seconds.
-   *
    * @param trackName key that identifies the track in the map.
    * @return this track's current position in seconds.
    * @throws AudioAssetNotFoundException
@@ -116,7 +108,6 @@ object MusicManager {
 
   /**
    * Sets this track's current position in seconds.
-   *
    * @param trackName key that identifies the track in the map.
    * @param position  target position in seconds.
    * @throws AudioAssetNotFoundException
@@ -129,9 +120,8 @@ object MusicManager {
   }
 
   /**
-   * Release resources, once you don't need the [Music] anymore.
+   * Releases resources held by the [Music] instances.
    * Accessing the sound after you disposed of it will result in undefined errors.
-   *
    * @param trackName key that identifies the track in the map.
    * @throws AudioAssetNotFoundException
    */

audio/src/main/kotlin/cyberpunk/audio/SoundManager.kt

@@ -13,7 +13,6 @@ object SoundManager {
 
   /**
    * Creates and loads a [Sound] onto the [sounds] structure.
-   *
    * @param soundName key that will identify this sound in the map.
    * @param path      sounds's path inside the assets folder.
    */
@@ -27,7 +26,6 @@ object SoundManager {
    * Plays the given sound, if present in the [sounds] map.
    * If no volume is specified (the second parameter), then the sound will be played with
    * the default volume, 1f.
-   *
    * @param soundName key that identifies the sound in the map.
    * @param volume    audio volume; ranges between [0, 1] and it's optional.
    * @param pitch     the pitch multiplier; ranges between [0.5 (slower), 2.0 (faster)] and it's optional.
@@ -47,7 +45,6 @@ object SoundManager {
    * Plays the given sound, if present in the [sounds] map.
    * If no volume is specified (the second parameter), then the sound will be played with
    * the default volume, 1f.
-   *
    * @param soundName key that identifies the sound in the map.
    * @param volume    audio volume; ranges between [0, 1] and it's optional.
    * @param pitch     the pitch multiplier; ranges between [0.5 (slower), 2.0 (faster)] and it's optional.
@@ -66,7 +63,6 @@ object SoundManager {
   /**
    * Stops all instances of the sound identified by the given [soundName].
    * If the instance doesn't exist, this method has no effect.
-   *
    * @param soundName key that identifies the sound in the map.
    * @throws AudioAssetNotFoundException
    */
@@ -78,7 +74,6 @@ object SoundManager {
   /**
    * Pauses all instances of the sound identified by the given [soundName].
    * If the instance doesn't exist, this method has no effect.
-   *
    * @param soundName key that identifies the sound in the map.
    * @throws AudioAssetNotFoundException
    */
@@ -90,7 +85,6 @@ object SoundManager {
   /**
    * Resumes all instances of the sound identified by the given [soundName].
    * If the instance doesn't exist, this method has no effect.
-   *
    * @param soundName key that identifies the sound in the map.
    * @throws AudioAssetNotFoundException
    */
@@ -100,9 +94,8 @@ object SoundManager {
     sounds[soundName]?.resume() ?: throw AudioAssetNotFoundException("$soundName not found.")
 
   /**
-   * Release resources, once you don't need the [Sound] anymore.
+   * Releases resources held by the [Sound] instances.
    * Accessing the sound after you disposed of it will result in undefined errors.
-   *
    * @param soundName key that identifies the sound in the map.
    * @throws AudioAssetNotFoundException
    */

camera/src/main/kotlin/cyberpunk/camera/CameraStyles.kt

@@ -8,7 +8,6 @@ import com.badlogic.gdx.math.Vector3
 
 /**
  * Centers the [Camera] in the middle of the screen, fiven the world coordinates.
- *
  * @param worldWidth  width of the world (world coordinates).
  * @param worldHeight height of the world (world coordinates).
  */
@@ -20,7 +19,6 @@ fun Camera.center(worldWidth: Int, worldHeight: Int) {
 /**
  * The [Camera] will follow the target coordinates rigidly.
  * Not suitable for all cases, as it may cause a very rough motion.
- *
  * @param targetPosition position of the target, where the camera will be also positioned to.
  */
 fun Camera.lockOn(targetPosition: Vector2) {
@@ -31,7 +29,6 @@ fun Camera.lockOn(targetPosition: Vector2) {
 /**
  * The [Camera] will rigidly follow the [targetPosition] horizontally, but will be
  * offset vertically by a [yOffset].
- *
  * @param targetPosition position of the target, where the camera will be also positioned to (horizontally).
  * @param yOffset camera's Y offset, relatively to the [targetPosition] Y.
  */
@@ -43,7 +40,6 @@ fun Camera.lockOnX(targetPosition: Vector2, yOffset: Float) {
 /**
  * The [Camera] will rigidly follow the [targetPosition] vertically, but will be
  * offset horizontally by a [xOffset].
- *
  * @param targetPosition position of the target, where the camera will be also positioned to (horizontally).
  * @param xOffset camera's X offset, relatively to the [targetPosition] X.
  */
@@ -54,9 +50,8 @@ fun Camera.lockOnY(targetPosition: Vector2, xOffset: Float) {
 
 /**
  * The [Camera] will follow a [targetPosition] with a smooth linear interpolation, based on a [lerp] amount.
- * The lower the lerp amount, the smoother - and thus slower - the following motion.
+ * The lower that interpolation amount, the smoother - and thus slower - the following motion.
  * The camera can also be offset by an [xOffset] and [yOffset] amounts, but that's optional.
- *
  * @param targetPosition  position of the target that the camera will be set on.
  * @param lerp            defines how smoothly the camera follows; ]0 (slowest), 1 (fastest)].
  * @param xOffset         camera's X offset, relatively to the [targetPosition] X.
@@ -73,7 +68,6 @@ fun Camera.lerpTo(targetPosition: Vector2, lerp: Float, xOffset: Float = 0f, yOf
 /**
  * Sets the [Camera] position to the given one and updates it.
  * Won't be called explicitly anywhere besides this class.
- *
  * @param newPosition new [Vector3] position for the camera.
  */
 private fun Camera.refresh(newPosition: Vector3) {

core/src/main/kotlin/cyberpunk/core/Graphics.kt

@@ -7,7 +7,6 @@ import com.badlogic.gdx.graphics.GL20
 
 /**
  * Clears the frame and depth buffers with the selected color.
- *
  * @param red red color value.
  * @param green green color value.
  * @param blue blue color value.

core/src/main/kotlin/cyberpunk/core/state/State.kt

@@ -9,15 +9,13 @@ interface State : InputProcessor {
   /**
    * Updates the state.
    * This is called every frame.
-   *
    * @param delta time elapsed since the last call to this method.
    */
   fun update(delta: Float)
 
   /**
    * Renders the state.
    * This is also called every frame, always after [State.update].
-   *
    * @param batch [Batch] used to render the state.
    */
   fun render(batch: Batch)
@@ -44,15 +42,13 @@ interface State : InputProcessor {
 
   /**
    * Resizes the state and any of its components.
-   *
    * @param width  new width.
    * @param height new height.
    */
   fun resize(width: Int, height: Int)
 
   /**
    * Unprojects screen coordinates into world coordinates.
-   *
    * @param screenX X in screen coordinates.
    * @param screenY Y in screen coordinates.
    * @return world coordinates.
@@ -61,7 +57,6 @@ interface State : InputProcessor {
 
   /**
    * Unprojects screen coordinates into world coordinates.
-   *
    * @param screenCoordinates (X, Y) screen coordinates.
    * @return world coordinates.
    */

core/src/main/kotlin/cyberpunk/core/state/StateAdapter.kt

@@ -5,29 +5,30 @@ import com.badlogic.gdx.math.Vector2
 
 abstract class StateAdapter(protected val stateManager: StateManager) : State {
 
-  /* State methods that absolutely must be overridden. */
-
+  /**
+   * State methods that absolutely must be overridden.
+   */
   override abstract fun update(delta: Float)
   override abstract fun render(batch: Batch)
   override abstract fun dispose()
 
-  /* State methods that may or may not be overridden. */
-
+  /**
+   * State methods that may or may not be overridden (no-op implementation).
+   */
   override fun resize(width: Int, height: Int) = Unit
   override fun hide() = Unit
   override fun pause() = Unit
   override fun resume() = Unit
 
-  /* State input conversion methods - should not be overridden. */
-
-  override fun unproject(screenCoordinates: Vector2) =
-    stateManager.viewport.unproject(screenCoordinates)
-
-  override fun unproject(screenX: Float, screenY: Float) =
-    this.unproject(Vector2(screenX, screenY))
-
-  /* InputProcessor methods that may or may not be overridden. */
+  /**
+   * State input conversion methods with default implementation.
+   */
+  override fun unproject(screenCoordinates: Vector2) = stateManager.viewport.unproject(screenCoordinates)
+  override fun unproject(screenX: Float, screenY: Float) = this.unproject(Vector2(screenX, screenY))
 
+  /**
+   * InputProcessor methods that may or may not be overridden.
+   */
   override fun keyDown(keycode: Int) = false
   override fun keyUp(keycode: Int) = false
   override fun keyTyped(character: Char) = false

core/src/main/kotlin/cyberpunk/core/state/StateManager.kt

@@ -12,7 +12,6 @@ import cyberpunk.core.transition.Transition
 
 /**
  * Initializes the [StateManager] with it a [Camera] and [Viewport].
- *
  * @param camera   camera that will use a virtual resolution.
  * @param viewport viewport that will adapt the game screen to the physical devices.
  */
@@ -54,7 +53,6 @@ class StateManager(val camera: Camera, val viewport: Viewport) {
   /**
    * Sets a [State] to be the currently running one. Optionally, pass
    * a [Transition] to make this change more pleasant.
-   *
    * @param state       new current state.
    * @param transition  optional transition used to move from states.
    */
@@ -75,7 +73,6 @@ class StateManager(val camera: Camera, val viewport: Viewport) {
   /**
    * Updates the [currentState], if there is one.
    * Also updates any on-going [Transition].
-   *
    * @param delta time elapsed between this moment and the last update call.
    */
   fun update(delta: Float) {
@@ -114,7 +111,6 @@ class StateManager(val camera: Camera, val viewport: Viewport) {
   /**
    * Resizes the [currentState], [nextState] and this class' [Viewport].
    * Here, the [FrameBuffer] objects are disposed manually and re-defined.
-   *
    * @param width  new screen width.
    * @param height new screen height.
    */
@@ -155,7 +151,6 @@ class StateManager(val camera: Camera, val viewport: Viewport) {
   /**
    * Utility extension function to wrap any [block] inside the
    * [FrameBuffer.begin] and [FrameBuffer.end] calls, for shortness.
-   *
    * @param block a [Unit] returning function.
    */
   private inline fun FrameBuffer.wrap(block: () -> Unit) {
@@ -165,7 +160,7 @@ class StateManager(val camera: Camera, val viewport: Viewport) {
   }
 
   /**
-   * Initialize the [FrameBuffer] objects and the [TextureRegion]s that will
+   * Initializes the [FrameBuffer] objects and the [TextureRegion]s that will
    * serve any running [Transition].
    */
   private fun setupFBOs() {
@@ -181,7 +176,6 @@ class StateManager(val camera: Camera, val viewport: Viewport) {
 
   /**
    * Resizes the [FrameBuffer] objects in every [StateManager.resize] call.
-   *
    * @param width   new screen width.
    * @param height  new screen height.
    */

core/src/main/kotlin/cyberpunk/core/transition/Transition.kt

@@ -26,21 +26,18 @@ interface Transition {
 
   /**
    * Checks whether or not this [Transition] is running.
-   *
    * @return true if it is running, false otherwise.
    */
   fun running(): Boolean = running
 
   /**
    * Checks whether or not this [Transition] is completed.
-   *
    * @return true if it is completed, false otherwise.
    */
   fun completed(): Boolean = !running
 
   /**
    * Updates the [Transition].
-   *
    * @param delta - time elapsed since the last call to update.
    */
   fun update(delta: Float)
@@ -50,7 +47,6 @@ interface Transition {
    * These textures were obtained using the Render-To-Texture (RTT) technique.
    * A [TextureRegion] is used instead of a texture because the framebuffer is upside down to normal textures,
    * as seen here: "http://www.gamefromscratch.com/post/2014/01/21/Rendering-a-3D-model-to-texture-in-LibGDX.aspx
-   *
    * @param batch   [Batch] used to render.
    * @param current current (or previous?) screen's [TextureRegion], rendered onto a frame buffer.
    * @param next    next screen's [TextureRegion], rendered onto a frame buffer.