From 0742efd1963b8b9e0b17797ceb3dd576a765ecf6 Mon Sep 17 00:00:00 2001 From: DustinLin <39450497+DustinLin@users.noreply.github.com> Date: Sat, 7 Sep 2024 21:36:47 -0700 Subject: [PATCH] [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 | 58 ++++++++++++++++++++++++++++++++++++++++---- src/field/pokemon.ts | 1 + 2 files changed, 54 insertions(+), 5 deletions(-) diff --git a/src/field/arena.ts b/src/field/arena.ts index 1e1df38af21..9f0a9691dee 100644 --- a/src/field/arena.ts +++ b/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 hasPokemonSource is the new weather from a pokemon + * @param weather {@linkcode WeatherType} new {@linkcode WeatherType} to set + * @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, 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, ...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 | 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, 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)); } diff --git a/src/field/pokemon.ts b/src/field/pokemon.ts index f522d50f357..35a33907850 100644 --- a/src/field/pokemon.ts +++ b/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[] = [];