From 5bd259335bc5a56ec819952655989cfc5aba8982 Mon Sep 17 00:00:00 2001
From: NightKev <34855794+DayKev@users.noreply.github.com>
Date: Sat, 7 Sep 2024 01:25:02 -0700
Subject: [PATCH] Move some comments to tsdocs, add tsdocs for `canMove()`

---
 src/phases/move-phase.ts | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/phases/move-phase.ts b/src/phases/move-phase.ts
index 507e45ac7b8..35be5513d9e 100644
--- a/src/phases/move-phase.ts
+++ b/src/phases/move-phase.ts
@@ -46,6 +46,11 @@ export class MovePhase extends BattlePhase {
     this.ignorePp = ignorePp ?? false;
   }
 
+  /**
+   * Checks if the pokemon is active, if the move is usable, and that the move is targetting something.
+   * @param ignoreDisableTags `true` to not check if the move is disabled
+   * @returns `true` if all the checks pass
+   */
   canMove(ignoreDisableTags?: boolean): boolean {
     return this.pokemon.isActive(true) && this.move.isUsable(this.pokemon, this.ignorePp, ignoreDisableTags) && !!this.targets.length;
   }
@@ -109,11 +114,11 @@ export class MovePhase extends BattlePhase {
     this.end();
   }
 
+  /** Check for cancellation edge cases - no targets remaining, or Moves.NONE is on the queue (TODO: when does this happen?) */
   resolveFinalPreMoveCancellationChecks() {
     const targets = this.getActiveTargetPokemon();
     const moveQueue = this.pokemon.getMoveQueue();
 
-    // Cancellation edge cases - no targets remaining, or Moves.NONE is on the queue (TODO: when does this happen?)
     if (targets.length === 0 || (moveQueue.length && moveQueue[0].move === Moves.NONE)) {
       this.showFailedText();
       this.cancelled = true;
@@ -124,9 +129,7 @@ export class MovePhase extends BattlePhase {
     return this.scene.getField(true).filter(p => this.targets.includes(p.getBattlerIndex()));
   }
 
-  /**
-   * Handles Sleep/Paralysis/Freeze rolls and side effects, along with lapsing volatile statuses.
-   */
+  /** Handles Sleep/Paralysis/Freeze rolls and side effects, along with lapsing volatile statuses. */
   resolvePreMoveStatusEffects() {
     if (!this.followUp && this.pokemon.status && !this.pokemon.status.isPostTurn()) {
       this.pokemon.status.incrementTurn();
@@ -368,10 +371,24 @@ export class MovePhase extends BattlePhase {
     }
   }
 
+  /**
+   * Handles the case where the move was cancelled or failed:
+   * - Uses PP if the move failed (not cancelled) and should use PP (failed moves are not affected by Pressure)
+   * - Records a cancelled OR failed move in move history, so Abilities like Truant don't trigger on the
+   *   next turn and soft-lock.
+   * - Lapses `MOVE_EFFECT` tags:
+   *   - Semi-invulnerable battler tags (Fly/Dive/etc.) are intended to lapse on move effects, but also need
+   *     to lapse on move failure/cancellation.
+   *
+   *     TODO: ...this seems weird.
+   * - Removes the second turn of charge moves
+   *
+   *   TODO: handle charge moves more gracefully
+   */
   handlePreMoveFailures() {
     if (this.cancelled || this.failed) {
       if (this.failed) {
-        const ppUsed = this.ignorePp ? 0 : 1; // note that failed move PP usage isn't affected by pressure
+        const ppUsed = this.ignorePp ? 0 : 1;
 
         if (ppUsed) {
           this.move.usePp();
@@ -380,17 +397,10 @@ export class MovePhase extends BattlePhase {
         this.scene.eventTarget.dispatchEvent(new MoveUsedEvent(this.pokemon?.id, this.move.getMove(), ppUsed));
       }
 
-      // Record a cancelled OR failed move in move history, so Abilities like Truant don't trigger on the
-      // next turn and soft-lock.
       this.pokemon.pushMoveHistory({ move: Moves.NONE, result: MoveResult.FAIL });
 
-      // Semi-invulnerable battler tags (Fly/Dive/etc.) are intended to lapse on move effects, but also need
-      // to lapse on move failure/cancellation.
-      // TODO: ...this seems weird.
       this.pokemon.lapseTags(BattlerTagLapseType.MOVE_EFFECT);
 
-      // Remove the second turn of charge moves
-      // TODO: handle charge moves more gracefully
       this.pokemon.getMoveQueue().shift();
     }
   }