More documentation.

src/dynamic_data/models/pokemon.rs

@@ -11,8 +11,7 @@ use crate::dynamic_data::models::battle::Battle;
 use crate::dynamic_data::models::damage_source::DamageSource;
 use crate::dynamic_data::models::learned_move::{LearnedMove, MoveLearnMethod};
 use crate::dynamic_data::script_handling::{ScriptSource, ScriptSourceData, ScriptWrapper};
-use crate::dynamic_data::{DynamicLibrary, Script, ScriptCategory, ScriptContainer, ScriptSet, VolatileScripts};
-use crate::static_data::AbilityIndex;
+use crate::dynamic_data::{DynamicLibrary, Script, ScriptCategory, ScriptContainer, ScriptSet, VolatileScriptsOwner};
 use crate::static_data::DataLibrary;
 use crate::static_data::Form;
 use crate::static_data::Gender;
@@ -20,95 +19,107 @@ use crate::static_data::Item;
 use crate::static_data::Nature;
 use crate::static_data::Species;
 use crate::static_data::{Ability, Statistic};
+use crate::static_data::{AbilityIndex, TypeIdentifier};
 use crate::static_data::{ClampedStatisticSet, StatisticSet};
 use crate::utils::Random;
 use crate::{script_hook, PkmnResult, StringKey};
 
-#[derive(Debug)]
-pub struct PokemonBattleData<'pokemon, 'library> {
-    battle: *mut Battle<'pokemon, 'library>,
-    battle_side_index: AtomicU8,
-    index: AtomicU8,
-    on_battle_field: AtomicBool,
-    seen_opponents: RwLock<Vec<Weak<Pokemon<'pokemon, 'library>>>>,
-}
-
-impl<'pokemon, 'library> PokemonBattleData<'pokemon, 'library> {
-    pub fn battle_mut(&mut self) -> Option<&mut Battle<'pokemon, 'library>> {
-        unsafe { self.battle.as_mut() }
-    }
-    pub fn battle(&self) -> Option<&Battle<'pokemon, 'library>> {
-        unsafe { self.battle.as_ref() }
-    }
-
-    pub fn battle_side_index(&self) -> u8 {
-        self.battle_side_index.load(Ordering::Relaxed)
-    }
-    pub fn index(&self) -> u8 {
-        self.index.load(Ordering::Relaxed)
-    }
-    pub fn on_battle_field(&self) -> bool {
-        self.on_battle_field.load(Ordering::Relaxed)
-    }
-    pub fn seen_opponents(&self) -> &RwLock<Vec<Weak<Pokemon<'pokemon, 'library>>>> {
-        &self.seen_opponents
-    }
-}
-
+/// An individual Pokemon as we know and love them.
 #[derive(Debug)]
 pub struct Pokemon<'own, 'library>
 where
     'own: 'library,
 {
+    /// The library data of the Pokemon.
     library: &'own DynamicLibrary,
+    /// The species of the Pokemon.
     species: &'own Species,
+    /// The form of the Pokemon.
     form: &'own Form,
 
+    /// An optional display species of the Pokemon. If this is set, the client should display this
+    /// species. An example of usage for this is the Illusion ability.
     display_species: Option<&'own Species>,
+    /// An optional display form of the Pokemon. If this is set, the client should display this
+    //  species. An example of usage for this is the Illusion ability.
     display_form: Option<&'own Form>,
 
+    /// The current level of the Pokemon.
     level: LevelInt,
+    /// The amount of experience of the Pokemon.
     experience: AtomicU32,
+    /// A unique random number for this Pokemon.
     unique_identifier: u32,
+
+    /// The gender of the Pokemon.
     gender: Gender,
+    /// The coloring of the Pokemon. Value 0 is the default, value 1 means shiny. Other values are
+    /// currently not used, and can be used for other implementations.
     coloring: u8,
+    /// The held item of the Pokemon.
     held_item: RwLock<Option<&'own Item>>,
+    /// The remaining health points of the Pokemon.
     current_health: AtomicU32,
 
+    /// The weight of the Pokemon in kilograms.
     weight: Atomic<f32>,
+    /// The height of the Pokemon in meters.
     height: Atomic<f32>,
 
-    stat_boost: ClampedStatisticSet<AtomicI8, -6, 6>,
+    /// The stats of the Pokemon when disregarding any stat boosts.
     flat_stats: StatisticSet<AtomicU32>,
+    /// The statistics boosts of the Pokemon. Will prevent the value from going above 6, and below
+    /// -6.
+    stat_boost: ClampedStatisticSet<AtomicI8, -6, 6>,
+    /// The stats of the Pokemon including the stat boosts
     boosted_stats: StatisticSet<AtomicU32>,
+    /// The [individual values](https://bulbapedia.bulbagarden.net/wiki/Individual_values) of the Pokemon.
     individual_values: ClampedStatisticSet<AtomicU8, 0, 31>,
+    /// The [effort values](https://bulbapedia.bulbagarden.net/wiki/Effort_values) of the Pokemon.
     effort_values: ClampedStatisticSet<AtomicU8, 0, 252>,
+    /// The [nature](https://bulbapedia.bulbagarden.net/wiki/Nature) of the Pokemon.
     nature: &'own Nature,
 
+    /// An optional nickname of the Pokemon.
     nickname: Option<String>,
 
+    /// An index of the ability to find the actual ability on the form.
     ability_index: AbilityIndex,
-    is_ability_overridden: bool,
+    /// An ability can be overriden to an arbitrary ability. This is for example used for the Mummy
+    /// ability.
     override_ability: Option<Ability>,
 
+    /// If in battle, we have additional data.
     battle_data: RwLock<Option<PokemonBattleData<'own, 'library>>>,
 
+    /// The moves the Pokemon has learned. This is of a set length of [`MAX_MOVES`]. Empty move slots
+    /// are defined by None.
     moves: RwLock<[Option<Arc<LearnedMove<'library>>>; MAX_MOVES]>,
+    /// Whether or not the Pokemon is allowed to gain experience.
     allowed_experience: bool,
 
-    types: Vec<u8>,
+    /// The current types of the Pokemon.
+    types: Vec<TypeIdentifier>,
+    /// Whether or not this Pokemon is an egg.
     is_egg: bool,
+    /// Whether or not this Pokemon was caught this battle.
     is_caught: bool,
 
+    /// The script for the held item.
     held_item_trigger_script: ScriptContainer,
+    /// The script for the ability.
     ability_script: ScriptContainer,
+    /// The script for the status.
     status_script: ScriptContainer,
+    /// The volatile status scripts of the Pokemon.
     volatile: Arc<ScriptSet>,
 
+    /// Data required for the Pokemon to be a script source.
     script_source_data: RwLock<ScriptSourceData>,
 }
 
 impl<'own, 'library> Pokemon<'own, 'library> {
+    /// Instantiates a new Pokemon.
     pub fn new(
         library: &'own DynamicLibrary,
         species: &'own Species,
@@ -155,7 +166,6 @@ impl<'own, 'library> Pokemon<'own, 'library> {
             nature,
             nickname: None,
             ability_index: ability,
-            is_ability_overridden: false,
             override_ability: None,
             battle_data: RwLock::new(None),
             moves: RwLock::new([None, None, None, None]),
@@ -176,15 +186,19 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         pokemon
     }
 
+    /// The library data of the Pokemon.
     pub fn library(&self) -> &'own DynamicLibrary {
         self.library
     }
+    /// The species of the Pokemon.
     pub fn species(&self) -> &'own Species {
         self.species
     }
+    /// The form of the Pokemon.
     pub fn form(&self) -> &'own Form {
         self.form
     }
+    /// The species that should be displayed to the user. This handles stuff like the Illusion ability.
     pub fn display_species(&self) -> &'own Species {
         if let Some(v) = self.display_species {
             v
@@ -192,6 +206,7 @@ impl<'own, 'library> Pokemon<'own, 'library> {
             self.species
         }
     }
+    /// The form that should be displayed to the user. This handles stuff like the Illusion ability.
     pub fn display_form(&self) -> &'own Form {
         if let Some(v) = self.display_form {
             v
@@ -199,25 +214,32 @@ impl<'own, 'library> Pokemon<'own, 'library> {
             self.form
         }
     }
-
+    /// The current level of the Pokemon.
     pub fn level(&self) -> LevelInt {
         self.level
     }
+    /// The amount of experience of the Pokemon.
     pub fn experience(&self) -> u32 {
         self.experience.load(Ordering::Relaxed)
     }
+    /// A unique random number for this Pokemon.
     pub fn unique_identifier(&self) -> u32 {
         self.unique_identifier
     }
+    /// The gender of the Pokemon.
     pub fn gender(&self) -> Gender {
         self.gender
     }
+    /// The coloring of the Pokemon. Value 0 is the default, value 1 means shiny. Other values are
+    /// currently not used, and can be used for other implementations.
     pub fn coloring(&self) -> u8 {
         self.coloring
     }
+    /// Checks whether the Pokemon is holding an item,
     pub fn held_item(&self) -> &RwLock<Option<&'own Item>> {
         &self.held_item
     }
+    /// Checks whether the Pokemon is holding a specific item.
     pub fn has_held_item(&self, name: &StringKey) -> bool {
         // Only true if we have an item, and the item name is the same as the requested item.
         if let Some(v) = self.held_item.read().deref() {
@@ -225,12 +247,15 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
         false
     }
+    /// Changes the held item of the Pokemon/
     pub fn set_held_item(&self, item: &'own Item) -> Option<&'own Item> {
         self.held_item.write().replace(item)
     }
+    /// Removes the held item from the Pokemon.
     pub fn remove_held_item(&self) -> Option<&'own Item> {
         self.held_item.write().take()
     }
+    /// Makes the Pokemon uses its held item.
     pub fn consume_held_item(&self) -> bool {
         if self.held_item.read().is_none() {
             return false;
@@ -244,42 +269,53 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         todo!();
     }
 
+    /// The remaining health points of the Pokemon.
     pub fn current_health(&self) -> u32 {
         self.current_health.load(Ordering::Relaxed)
     }
+    /// The max health points of the Pokemon.
     pub fn max_health(&self) -> u32 {
         self.boosted_stats.hp()
     }
+    /// The weight of the Pokemon in kilograms.
     pub fn weight(&self) -> f32 {
         self.weight.load(Ordering::Relaxed)
     }
+    /// The height of the Pokemon in meters.
     pub fn height(&self) -> f32 {
         self.height.load(Ordering::Relaxed)
     }
+    /// An optional nickname of the Pokemon.
     pub fn nickname(&self) -> &Option<String> {
         &self.nickname
     }
+    /// An index of the ability to find the actual ability on the form.
     pub fn real_ability(&self) -> &AbilityIndex {
         &self.ability_index
     }
-    pub fn types(&self) -> &Vec<u8> {
+    /// The current types of the Pokemon.
+    pub fn types(&self) -> &Vec<TypeIdentifier> {
         &self.types
     }
+    /// The moves the Pokemon has learned. This is of a set length of [`MAX_MOVES`]. Empty move slots
+    /// are defined by None.
     pub fn learned_moves(&self) -> &RwLock<[Option<Arc<LearnedMove<'library>>>; MAX_MOVES]> {
         &self.moves
     }
-    pub fn status(&self) -> &ScriptContainer {
-        &self.status_script
-    }
+
+    /// The stats of the Pokemon when disregarding any stat boosts.
     pub fn flat_stats(&self) -> &StatisticSet<AtomicU32> {
         &self.flat_stats
     }
+    /// The stats of the Pokemon including the stat boosts
     pub fn boosted_stats(&self) -> &StatisticSet<AtomicU32> {
         &self.boosted_stats
     }
+    /// Get the stat boosts for a specific stat.
     pub fn stat_boost(&self, stat: Statistic) -> i8 {
         self.stat_boost.get_stat(stat)
     }
+    /// Change a boosted stat by a certain amount.
     pub fn change_stat_boost(&self, stat: Statistic, mut diff_amount: i8, self_inflicted: bool) -> bool {
         let mut prevent = false;
         script_hook!(
@@ -328,13 +364,16 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         return changed;
     }
 
+    /// The [individual values](https://bulbapedia.bulbagarden.net/wiki/Individual_values) of the Pokemon.
     pub fn individual_values(&self) -> &ClampedStatisticSet<AtomicU8, 0, 31> {
         &self.individual_values
     }
+    /// The [effort values](https://bulbapedia.bulbagarden.net/wiki/Effort_values) of the Pokemon.
     pub fn effort_values(&self) -> &ClampedStatisticSet<AtomicU8, 0, 252> {
         &self.effort_values
     }
 
+    /// Gets the battle the battle is currently in.
     pub fn get_battle(&self) -> Option<&Battle<'own, 'library>> {
         let r = self.battle_data.read();
         if let Some(data) = &r.deref() {
@@ -343,20 +382,24 @@ impl<'own, 'library> Pokemon<'own, 'library> {
             None
         }
     }
+    /// Get the index of the side of the battle the Pokemon is in. Only returns a value if the Pokemon
+    /// is on the battlefield.
     pub fn get_battle_side_index(&self) -> Option<u8> {
         self.battle_data.read().as_ref().map(|data| data.battle_side_index())
     }
+    /// Get the index of the slot on the side of the battle the Pokemon is in. Only returns a value
+    /// if the Pokemon is on the battlefield.
     pub fn get_battle_index(&self) -> Option<u8> {
         self.battle_data.read().as_ref().map(|data| data.index())
     }
+    /// Returns whether something overrides the ability.
     pub fn is_ability_overriden(&self) -> bool {
-        self.is_ability_overridden
+        self.override_ability.is_some()
     }
+    /// Returns the currently active ability.
     pub fn active_ability(&self) -> &Ability {
-        if self.is_ability_overridden {
-            if let Some(v) = &self.override_ability {
-                return v;
-            }
+        if let Some(v) = &self.override_ability {
+            return v;
         }
         self.library
             .static_data()
@@ -365,33 +408,41 @@ impl<'own, 'library> Pokemon<'own, 'library> {
             .unwrap()
     }
 
+    /// The script for the status.
+    pub fn status(&self) -> &ScriptContainer {
+        &self.status_script
+    }
+
+    /// Returns the script for the currently active ability.
     pub fn ability_script(&self) -> &ScriptContainer {
         &self.ability_script
     }
 
-    // pub fn seen_opponents(&self) -> &RwLock<Option<PokemonBattleData<'own, 'library>>> {
-    //     &self.battle_data.read
-    // }
+    /// Whether or not the Pokemon is allowed to gain experience.
     pub fn allowed_experience_gain(&self) -> bool {
         self.allowed_experience
     }
 
+    /// The [nature](https://bulbapedia.bulbagarden.net/wiki/Nature) of the Pokemon.
     pub fn nature(&self) -> &'own Nature {
         self.nature
     }
 
+    /// Calculates the flat stats on the Pokemon.
     pub fn recalculate_flat_stats(&self) {
         self.library
             .stat_calculator()
             .calculate_flat_stats(self, &self.flat_stats);
         self.recalculate_boosted_stats();
     }
+    /// Calculates the boosted stats on the Pokemon.
     pub fn recalculate_boosted_stats(&self) {
         self.library
             .stat_calculator()
             .calculate_boosted_stats(self, &self.boosted_stats);
     }
 
+    /// Change the species of the Pokemon.
     pub fn change_species(&mut self, species: &'own Species, form: &'own Form) {
         self.species = species;
         self.form = form;
@@ -424,6 +475,7 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Change the form of the Pokemon.
     pub fn change_form(&mut self, form: &'own Form) {
         if std::ptr::eq(self.form, form) {
             return;
@@ -474,14 +526,17 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Whether or not the Pokemon is useable in a battle.
     pub fn is_usable(&self) -> bool {
         !self.is_caught && !self.is_egg && !self.is_fainted()
     }
 
+    /// Returns whether the Pokemon is fainted.
     pub fn is_fainted(&self) -> bool {
         self.current_health() == 0
     }
 
+    /// Sets the current battle the Pokemon is in.
     pub fn set_battle_data(&self, battle: *mut Battle<'own, 'library>, battle_side_index: u8) {
         let mut w = self.battle_data.write();
         if let Some(battle_data) = w.deref_mut() {
@@ -498,6 +553,7 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Sets whether or not the Pokemon is on the battlefield.
     pub fn set_on_battlefield(&self, value: bool) {
         let r = self.battle_data.read();
         if let Some(data) = &mut r.deref() {
@@ -510,6 +566,7 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Sets the index of the slot of the side the Pokemon is on.
     pub fn set_battle_index(&self, index: u8) {
         let r = self.battle_data.read();
         if let Some(data) = r.deref() {
@@ -517,10 +574,12 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Whether or not the Pokemon is on the battlefield.
     pub fn is_on_battlefield(&self) -> bool {
         self.battle_data.read().is_some_and(|a| a.on_battle_field())
     }
 
+    /// Marks an opponent as seen, for use in experience gain.
     pub fn mark_opponent_as_seen(&self, pokemon: Weak<Pokemon<'own, 'library>>) {
         let r = self.battle_data.read();
         if let Some(battle_data) = &r.deref() {
@@ -534,6 +593,7 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Damages the Pokemon by a certain amount of damage, from a specific damage source.
     pub fn damage(&self, mut damage: u32, source: DamageSource) {
         if damage > self.current_health() {
             damage = self.current_health();
@@ -563,7 +623,8 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
-    pub fn on_faint(&self, source: DamageSource) {
+    /// Triggers when the Pokemon faints.
+    fn on_faint(&self, source: DamageSource) {
         let r = self.battle_data.read();
         if let Some(battle_data) = r.deref() {
             if let Some(battle) = battle_data.battle() {
@@ -581,6 +642,7 @@ impl<'own, 'library> Pokemon<'own, 'library> {
         }
     }
 
+    /// Learn a move.
     pub fn learn_move(&self, move_name: &StringKey, learn_method: MoveLearnMethod) {
         let mut learned_moves = self.learned_moves().write();
         let move_pos = learned_moves.iter().position(|a| a.is_none());
@@ -592,6 +654,49 @@ impl<'own, 'library> Pokemon<'own, 'library> {
     }
 }
 
+/// The data of the Pokemon related to being in a battle.
+#[derive(Debug)]
+pub struct PokemonBattleData<'pokemon, 'library> {
+    /// The battle data of the Pokemon
+    battle: *mut Battle<'pokemon, 'library>,
+    /// The index of the side of the Pokemon
+    battle_side_index: AtomicU8,
+    /// The index of the slot on the side of the Pokemon.
+    index: AtomicU8,
+    /// Whether or not the Pokemon is on the battlefield.
+    on_battle_field: AtomicBool,
+    /// A list of opponents the Pokemon has seen this battle.
+    seen_opponents: RwLock<Vec<Weak<Pokemon<'pokemon, 'library>>>>,
+}
+
+impl<'pokemon, 'library> PokemonBattleData<'pokemon, 'library> {
+    /// The battle data of the Pokemon
+    pub fn battle_mut(&mut self) -> Option<&mut Battle<'pokemon, 'library>> {
+        unsafe { self.battle.as_mut() }
+    }
+    /// The battle data of the Pokemon
+    pub fn battle(&self) -> Option<&Battle<'pokemon, 'library>> {
+        unsafe { self.battle.as_ref() }
+    }
+
+    /// The index of the side of the Pokemon
+    pub fn battle_side_index(&self) -> u8 {
+        self.battle_side_index.load(Ordering::Relaxed)
+    }
+    /// The index of the slot on the side of the Pokemon.
+    pub fn index(&self) -> u8 {
+        self.index.load(Ordering::Relaxed)
+    }
+    /// Whether or not the Pokemon is on the battlefield.
+    pub fn on_battle_field(&self) -> bool {
+        self.on_battle_field.load(Ordering::Relaxed)
+    }
+    /// A list of opponents the Pokemon has seen this battle.
+    pub fn seen_opponents(&self) -> &RwLock<Vec<Weak<Pokemon<'pokemon, 'library>>>> {
+        &self.seen_opponents
+    }
+}
+
 impl<'own, 'library> ScriptSource<'own> for Pokemon<'own, 'library> {
     fn get_script_count(&self) -> usize {
         let mut c = 3;
@@ -624,7 +729,7 @@ impl<'own, 'library> ScriptSource<'own> for Pokemon<'own, 'library> {
     }
 }
 
-impl<'own, 'library> VolatileScripts<'own> for Pokemon<'own, 'library> {
+impl<'own, 'library> VolatileScriptsOwner<'own> for Pokemon<'own, 'library> {
     fn volatile_scripts(&self) -> &Arc<ScriptSet> {
         &self.volatile
     }