From c9356237cbb39ab289afcf2539c2c486c10e4ef6 Mon Sep 17 00:00:00 2001
From: Bertie690 <taylormw163@gmail.com>
Date: Mon, 9 Jun 2025 19:15:44 -0400
Subject: [PATCH] Battler Tags doc fixes

---
 src/data/battler-tags.ts | 39 +++++++++++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/src/data/battler-tags.ts b/src/data/battler-tags.ts
index 192acecc6c9..50b8227667f 100644
--- a/src/data/battler-tags.ts
+++ b/src/data/battler-tags.ts
@@ -44,19 +44,49 @@ import { isNullOrUndefined } from "#app/utils/common";
 import { MoveUseMode } from "#enums/move-use-mode";
 import { invalidEncoreMoves } from "./moves/invalid-moves";
 
+/**
+ * Enum representing the possible ways a given BattlerTag can activate and/or tick down.
+ * Each tag can have multiple different behaviors attached to different lapse types.
+ */
 export enum BattlerTagLapseType {
+  // TODO: This is unused...
   FAINT,
+  /**
+   * Tag activate before the holder uses a non-virtual move, possibly interrupting its action.
+   * @see MoveUseMode for more information
+   */
   MOVE,
+  /** Tag activates before the holder uses **any** move, triggering effects or interrupting its action. */
   PRE_MOVE,
+  /** Tag activates immediately after the holder's move finishes triggering (successful or not). */
   AFTER_MOVE,
+  /**
+   * Tag activates before move effects are applied.
+   * TODO: Stop using this as a catch-all "semi-invulnerability" tag
+   */
   MOVE_EFFECT,
+  /** Tag activates at the end of the turn. */
   TURN_END,
+  /**
+   * Tag activates after the holder is hit by an attack, but before damage is applied.
+   * Occurs even if the user's {@linkcode SubstituteTag | Substitute} is hit.
+   */
   HIT,
-  /** Tag lapses AFTER_HIT, applying its effects even if the user faints */
+  /**
+   * Tag activates after the holder is directly hit by an attack.
+   * Does **not** occur on hits to the holder's {@linkcode SubstituteTag | Substitute},
+   * but still triggers on being KO'd.
+   */
   AFTER_HIT,
+  /** The tag has some other custom activation or removal condition. */
   CUSTOM,
 }
 
+/**
+ * A {@linkcode BattlerTag} represents a semi-persistent effect that can be attached to a {@linkcode Pokemon}.
+ * Tags can trigger various effects throughout a turn, and are cleared on switching out
+ * or through their respective {@linkcode BattlerTag.lapse | lapse} methods.
+ */
 export class BattlerTag {
   public tagType: BattlerTagType;
   public lapseTypes: BattlerTagLapseType[];
@@ -93,7 +123,7 @@ export class BattlerTag {
 
   /**
    * Tick down this {@linkcode BattlerTag}'s duration.
-   * @returns `true` if the tag should be kept (`turnCount` > 0`)
+   * @returns `true` if the tag should be kept (`turnCount > 0`)
    */
   lapse(_pokemon: Pokemon, _lapseType: BattlerTagLapseType): boolean {
     // TODO: Maybe flip this (return `true` if tag needs removal)
@@ -382,10 +412,7 @@ export class GorillaTacticsTag extends MoveRestrictionBattlerTag {
   override canAdd(pokemon: Pokemon): boolean {
     // Choice items ignore struggle, so Gorilla Tactics should too
     const lastSelectedMove = pokemon.getLastNonVirtualMove();
-    return (
-      !isNullOrUndefined(lastSelectedMove) &&
-      lastSelectedMove.move !== MoveId.STRUGGLE
-    );
+    return !isNullOrUndefined(lastSelectedMove) && lastSelectedMove.move !== MoveId.STRUGGLE;
   }
 
   /**