[DOCS] adding JSDocs to `arena.ts` (#3590)

* adding some docs

* Update src/field/pokemon.ts

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

* seems like battleStats changed to statStages

* Apply suggestions from code review

editing doc text

Co-authored-by: flx-sta <50131232+flx-sta@users.noreply.github.com>

* Update tsdocs, convert comment to tsdoc in `pokemon.ts`

---------

Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>
Co-authored-by: flx-sta <50131232+flx-sta@users.noreply.github.com>

src/field/arena.ts

@@ -60,7 +60,7 @@ export class Arena {
     this.scene.arenaBg.setTexture(`${biomeKey}_bg`);
     this.scene.arenaBgTransition.setTexture(`${biomeKey}_bg`);
 
-    // Redo this on initialise because during save/load the current wave isn't always
+    // Redo this on initialize because during save/load the current wave isn't always
     // set correctly during construction
     this.updatePoolsForTimeOfDay();
   }
@@ -289,7 +289,7 @@ export class Arena {
 
   /**
    * Sets weather to the override specified in overrides.ts
-   * @param weather new weather to set of type WeatherType
+   * @param weather new {@linkcode WeatherType} to set
    * @returns true to force trySetWeather to return true
    */
   trySetWeatherOverride(weather: WeatherType): boolean {
@@ -301,8 +301,8 @@ export class Arena {
 
   /**
    * Attempts to set a new weather to the battle
-   * @param weather new weather to set of type WeatherType
+   * @param weather {@linkcode WeatherType} new {@linkcode WeatherType} to set
-   * @param hasPokemonSource is the new weather from a pokemon
+   * @param hasPokemonSource boolean if the new weather is from a pokemon
    * @returns true if new weather set, false if no weather provided or attempting to set the same weather as currently in use
    */
   trySetWeather(weather: WeatherType, hasPokemonSource: boolean): boolean {
@@ -573,6 +573,12 @@ export class Arena {
     this.ignoreAbilities = ignoreAbilities;
   }
 
+  /**
+   * Applies each `ArenaTag` in this Arena, based on which side (self, enemy, or both) is passed in as a parameter
+   * @param tagType Either an {@linkcode ArenaTagType} string, or an actual {@linkcode ArenaTag} class to filter which ones to apply
+   * @param side {@linkcode ArenaTagSide} which side's arena tags to apply
+   * @param args array of parameters that the called upon tags may need
+   */
   applyTagsForSide(tagType: ArenaTagType | Constructor<ArenaTag>, side: ArenaTagSide, ...args: unknown[]): void {
     let tags = typeof tagType === "string"
       ? this.tags.filter(t => t.tagType === tagType)
@@ -583,11 +589,28 @@ export class Arena {
     tags.forEach(t => t.apply(this, args));
   }
 
+  /**
+   * Applies the specified tag to both sides (ie: both user and trainer's tag that match the Tag specified)
+   * by calling {@linkcode applyTagsForSide()}
+   * @param tagType Either an {@linkcode ArenaTagType} string, or an actual {@linkcode ArenaTag} class to filter which ones to apply
+   * @param args array of parameters that the called upon tags may need
+   */
   applyTags(tagType: ArenaTagType | Constructor<ArenaTag>, ...args: unknown[]): void {
     this.applyTagsForSide(tagType, ArenaTagSide.BOTH, ...args);
   }
 
-  addTag(tagType: ArenaTagType, turnCount: integer, sourceMove: Moves | undefined, sourceId: integer, side: ArenaTagSide = ArenaTagSide.BOTH, quiet: boolean = false, targetIndex?: BattlerIndex): boolean {
+  /**
+   * Adds a new tag to the arena
+   * @param tagType {@linkcode ArenaTagType} the tag being added
+   * @param turnCount How many turns the tag lasts
+   * @param sourceMove {@linkcode Moves} the move the tag came from, or `undefined` if not from a move
+   * @param sourceId The ID of the pokemon in play the tag came from (see {@linkcode BattleScene.getPokemonById})
+   * @param side {@linkcode ArenaTagSide} which side(s) the tag applies to
+   * @param quiet If a message should be queued on screen to announce the tag being added
+   * @param targetIndex The {@linkcode BattlerIndex} of the target pokemon
+   * @returns `false` if there already exists a tag of this type in the Arena
+   */
+  addTag(tagType: ArenaTagType, turnCount: number, sourceMove: Moves | undefined, sourceId: number, side: ArenaTagSide = ArenaTagSide.BOTH, quiet: boolean = false, targetIndex?: BattlerIndex): boolean {
     const existingTag = this.getTagOnSide(tagType, side);
     if (existingTag) {
       existingTag.onOverlap(this);
@@ -600,6 +623,7 @@ export class Arena {
       return false;
     }
 
+    // creates a new tag object
     const newTag = getArenaTag(tagType, turnCount || 0, sourceMove, sourceId, targetIndex, side);
     if (newTag) {
       this.tags.push(newTag);
@@ -613,6 +637,11 @@ export class Arena {
     return true;
   }
 
+  /**
+   * Attempts to get a tag from the Arena via {@linkcode getTagOnSide} that applies to both sides
+   * @param tagType The {@linkcode ArenaTagType} or {@linkcode ArenaTag} to get
+   * @returns either the {@linkcode ArenaTag}, or `undefined` if it isn't there
+   */
   getTag(tagType: ArenaTagType | Constructor<ArenaTag>): ArenaTag | undefined {
     return this.getTagOnSide(tagType, ArenaTagSide.BOTH);
   }
@@ -621,16 +650,35 @@ export class Arena {
     return !!this.getTag(tagType);
   }
 
+  /**
+   * Attempts to get a tag from the Arena from a specific side (the tag passed in has to either apply to both sides, or the specific side only)
+   *
+   * eg: `MIST` only applies to the user's side, while `MUD_SPORT` applies to both user and enemy side
+   * @param tagType The {@linkcode ArenaTagType} or {@linkcode ArenaTag} to get
+   * @param side The {@linkcode ArenaTagSide} to look at
+   * @returns either the {@linkcode ArenaTag}, or `undefined` if it isn't there
+   */
   getTagOnSide(tagType: ArenaTagType | Constructor<ArenaTag>, side: ArenaTagSide): ArenaTag | undefined {
     return typeof(tagType) === "string"
       ? this.tags.find(t => t.tagType === tagType && (side === ArenaTagSide.BOTH || t.side === ArenaTagSide.BOTH || t.side === side))
       : this.tags.find(t => t instanceof tagType && (side === ArenaTagSide.BOTH || t.side === ArenaTagSide.BOTH || t.side === side));
   }
 
+  /**
+   * Uses {@linkcode findTagsOnSide} to filter (using the parameter function) for specific tags that apply to both sides
+   * @param tagPredicate a function mapping {@linkcode ArenaTag}s to `boolean`s
+   * @returns array of {@linkcode ArenaTag}s from which the Arena's tags return true and apply to both sides
+   */
   findTags(tagPredicate: (t: ArenaTag) => boolean): ArenaTag[] {
     return this.findTagsOnSide(tagPredicate, ArenaTagSide.BOTH);
   }
 
+  /**
+   * Returns specific tags from the arena that pass the `tagPredicate` function passed in as a parameter, and apply to the given side
+   * @param tagPredicate a function mapping {@linkcode ArenaTag}s to `boolean`s
+   * @param side The {@linkcode ArenaTagSide} to look at
+   * @returns array of {@linkcode ArenaTag}s from which the Arena's tags return `true` and apply to the given side
+   */
   findTagsOnSide(tagPredicate: (t: ArenaTag) => boolean, side: ArenaTagSide): ArenaTag[] {
     return this.tags.filter(t => tagPredicate(t) && (side === ArenaTagSide.BOTH || t.side === ArenaTagSide.BOTH || t.side === side));
   }

src/field/pokemon.ts

@@ -4501,6 +4501,7 @@ export interface AttackMoveResult {
 }
 
 export class PokemonSummonData {
+  /** [Atk, Def, SpAtk, SpDef, Spd, Acc, Eva] */
   public statStages: number[] = [ 0, 0, 0, 0, 0, 0, 0 ];
   public moveQueue: QueuedMove[] = [];
   public tags: BattlerTag[] = [];