From 1b3a1f3f3c45949dd2dde5e33ab4a8d63de8226d Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Tue, 8 Sep 2020 11:32:36 +0300
Subject: [PATCH 01/11] Further refactoring in PokeBattle_Pokemon

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 222 +++++++++++-------
 1 file changed, 134 insertions(+), 88 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 491517874..5404f8d5c 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -1,21 +1,36 @@
 # This class stores data on each Pokémon. Refer to $Trainer.party for an array
 # of each Pokémon in the Trainer's current party.
 class PokeBattle_Pokemon
-  attr_accessor :name        # Nickname
-  attr_reader   :species     # Species (National Pokedex number)
-  attr_reader   :exp         # Current experience points
-  attr_reader   :hp          # Current HP
-  attr_reader   :totalhp     # Current Total HP
-  attr_reader   :attack      # Current Attack stat
-  attr_reader   :defense     # Current Defense stat
-  attr_reader   :speed       # Current Speed stat
-  attr_reader   :spatk       # Current Special Attack stat
-  attr_reader   :spdef       # Current Special Defense stat
-  attr_accessor :status      # Status problem (PBStatuses)
-  attr_accessor :statusCount # Sleep count/Toxic flag
-  attr_accessor :abilityflag # Forces the first/second/hidden (0/1/2) ability
-  attr_accessor :genderflag  # Forces male (0) or female (1)
-  attr_accessor :natureflag  # Forces a particular nature
+  # @return [String] nickname
+  attr_accessor :name
+  # @return [Integer] national Pokédex number
+  attr_reader   :species
+  # @return [Integer] current experience points
+  attr_reader   :exp
+  # @return [Integer] current HP
+  attr_reader   :hp
+  # @return [Integer] current Total HP
+  attr_reader   :totalhp
+  # @return [Integer] current Attack stat
+  attr_reader   :attack
+  # @return [Integer] current Defense stat
+  attr_reader   :defense
+  # @return [Integer] current Speed stat
+  attr_reader   :speed
+  # @return [Integer] current Special Attack stat
+  attr_reader   :spatk
+  # @return [Integer] current Special Defense stat
+  attr_reader   :spdef
+  # @return [Integer] status problem (from PBStatus)
+  attr_accessor :status
+  # @return [Integer] sleep count / toxic flag
+  attr_accessor :statusCount
+  # @return [0, 1, 2] forces the first / second / hidden ability
+  attr_accessor :abilityflag
+  # @return [0, 1] forces male (0) or female (1)
+  attr_accessor :genderflag
+  # @return [Integer] forces a particular nature (nature ID)
+  attr_accessor :natureflag
   attr_accessor :natureOverride   # Overrides nature's stat-changing effects
   attr_accessor :shinyflag   # Forces the shininess (true/false)
   attr_accessor :moves       # Moves (PBMove)
@@ -59,38 +74,41 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Ownership, obtained information
   #=============================================================================
-  # Returns the public portion of the original trainer's ID.
+
+  # @return [Integer] public portion of the original trainer's ID
   def publicID
-    return @trainerID&0xFFFF
+    return @trainerID & 0xFFFF
   end
 
-  # Returns whether the specified Trainer is NOT this Pokémon's original trainer.
+  # @param trainer [PokeBattle_Trainer] the trainer to compare to the OT
+  # @return [Boolean] whether the trainer and OT don't match
   def foreign?(trainer)
-    return @trainerID!=trainer.id || @ot!=trainer.name
+    return @trainerID != trainer.id || @ot != trainer.name
   end
   alias isForeign? foreign?
 
-  # Returns the gender of this Pokémon's original trainer (2=unknown).
+  # @return [0, 1, 2] gender of this Pokémon original trainer (0 = male, 1 = female, 2 = unknown)
   def otgender
     return @otgender || 2
   end
 
-  # Returns this Pokémon's level when this Pokémon was obtained.
+  # @return [Integer] this Pokémon's level when it was obtained
   def obtainLevel
     return @obtainLevel || 0
   end
 
-  # Returns the time when this Pokémon was obtained.
+  # @return [Time] time when this Pokémon was obtained
   def timeReceived
     return @timeReceived ? Time.at(@timeReceived) : Time.gm(2000)
   end
 
-  # Sets the time when this Pokémon was obtained (in seconds since Unix epoch).
+  # Sets the time when this Pokémon was obtained.
+  # @param value [Integer, Time, #to_i] time in seconds since Unix epoch
   def timeReceived=(value)
     @timeReceived = value.to_i
   end
 
-  # Returns the time when this Pokémon hatched.
+  # @return [Time] time when this Pokémon hatched
   def timeEggHatched
     if obtainMode==1
       return @timeEggHatched ? Time.at(@timeEggHatched) : Time.gm(2000)
@@ -99,7 +117,8 @@ class PokeBattle_Pokemon
     end
   end
 
-  # Sets the time when this Pokémon hatched (in seconds since Unix epoch).
+  # Sets the time when this Pokémon hatched.
+  # @param value [Integer, Time, #to_i] time in seconds since Unix epoch
   def timeEggHatched=(value)
     @timeEggHatched = value.to_i
   end
@@ -107,13 +126,15 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Level
   #=============================================================================
-  # Returns this Pokémon's level.
+
+  # @return [Integer] this Pokémon's level
   def level
     @level = PBExperience.pbGetLevelFromExperience(@exp,self.growthrate) if !@level
     return @level
   end
 
   # Sets this Pokémon's level.
+  # @param value [Integer] new level (between 1 and the maximum level)
   def level=(value)
     if value<1 || value>PBExperience.maxLevel
       raise ArgumentError.new(_INTL("The level number ({1}) is invalid.",value))
@@ -123,42 +144,44 @@ class PokeBattle_Pokemon
   end
 
   # Sets this Pokémon's Exp. Points.
+  # @param value [Integer] new experience points
   def exp=(value)
     @exp = value
     @level = nil
   end
 
-  # Returns whether this Pokémon is an egg.
+  # @return [Boolean] whether this Pokémon is an egg
   def egg?
-    return @eggsteps>0
+    return @eggsteps > 0
   end
   alias isEgg? egg?
 
-  # Returns this Pokémon's growth rate.
+  # @return [Integer] this Pokémon's growth rate (from PBGrowthRates)
   def growthrate
     return pbGetSpeciesData(@species,formSimple,SpeciesGrowthRate)
   end
 
-  # Returns this Pokémon's base Experience value.
+  # @return [Integer] this Pokémon's base Experience value
   def baseExp
     return pbGetSpeciesData(@species,formSimple,SpeciesBaseExp)
   end
 
-  # Returns a number between 0 and 1 indicating how much of the current level's
-  # Exp this Pokémon has.
+  # @return [Float] number between 0 and 1 indicating how much of the current level's
+  #   Exp this Pokémon has
   def expFraction
     l = self.level
-    return 0.0 if l>=PBExperience.maxLevel
+    return 0.0 if l >= PBExperience.maxLevel
     gr = self.growthrate
-    startexp = PBExperience.pbGetStartExperience(l,gr)
-    endexp   = PBExperience.pbGetStartExperience(l+1,gr)
-    return 1.0*(@exp-startexp)/(endexp-startexp)
+    startexp = PBExperience.pbGetStartExperience(l, gr)
+    endexp   = PBExperience.pbGetStartExperience(l + 1, gr)
+    return 1.0 * (@exp - startexp) / (endexp - startexp)
   end
 
   #=============================================================================
   # Gender
   #=============================================================================
-  # Returns this Pokémon's gender. 0=male, 1=female, 2=genderless
+
+  # @return [0, 1, 2] this Pokémon's gender (0 = male, 1 = female, 2 = genderless)
   def gender
     # Return sole gender option for all male/all female/genderless species
     genderRate = pbGetSpeciesData(@species,formSimple,SpeciesGenderRate)
@@ -168,96 +191,106 @@ class PokeBattle_Pokemon
     when PBGenderRates::Genderless;   return 2
     end
     # Return gender for species that can be male or female
-    return @genderflag if @genderflag && (@genderflag==0 || @genderflag==1)
-    return ((@personalID&0xFF)<PBGenderRates.genderByte(genderRate)) ? 1 : 0
+    return @genderflag if @genderflag && (@genderflag == 0 || @genderflag == 1)
+    return ((@personalID & 0xFF) < PBGenderRates.genderByte(genderRate)) ? 1 : 0
   end
 
-  # Returns whether this Pokémon species is restricted to only ever being one
-  # gender (or genderless).
+  # @return [Boolean] whether this Pokémon species is restricted to only ever being one
+  #   gender (or genderless)
   def singleGendered?
     genderRate = pbGetSpeciesData(@species,formSimple,SpeciesGenderRate)
-    return genderRate==PBGenderRates::AlwaysMale ||
-           genderRate==PBGenderRates::AlwaysFemale ||
-           genderRate==PBGenderRates::Genderless
+    return genderRate == PBGenderRates::AlwaysMale ||
+           genderRate == PBGenderRates::AlwaysFemale ||
+           genderRate == PBGenderRates::Genderless
   end
   alias isSingleGendered? singleGendered?
 
-  # Returns whether this Pokémon is male.
+  # @return [Boolean] whether this Pokémon is male
   def male?
-    return self.gender==0
+    return self.gender == 0
   end
   alias isMale? male?
 
-  # Returns whether this Pokémon is female.
+  # @return [Boolean] whether this Pokémon is female
   def female?
-    return self.gender==1
+    return self.gender == 1
   end
   alias isFemale? female?
 
-  # Returns whether this Pokémon is genderless.
+  # @return [Boolean] whether this Pokémon is genderless
   def genderless?
-    return self.gender==2
+    return self.gender == 2
   end
   alias isGenderless? genderless?
 
   # Sets this Pokémon's gender to a particular gender (if possible).
+  # @param value [0, 1, 2] new gender (0 = male, 1 = female, 2 = genderless)
   def setGender(value)
     @genderflag = value if !singleGendered?
   end
 
+  # Makes this Pokémon male.
   def makeMale;   setGender(0); end
+  # Makes this Pokémon female.
   def makeFemale; setGender(1); end
 
   #=============================================================================
   # Ability
   #=============================================================================
-  # Returns the index of this Pokémon's ability.
+
+  # @return [Integer] the index of this Pokémon's ability
   def abilityIndex
-    return @abilityflag || (@personalID&1)
+    return @abilityflag || (@personalID & 1)
   end
 
-  # Returns the ID of this Pokémon's ability.
+  # @return [Integer] the ID of this Pokémon's ability
   def ability
     abilIndex = abilityIndex
     # Hidden ability
-    if abilIndex>=2
+    if abilIndex >= 2
       hiddenAbil = pbGetSpeciesData(@species,formSimple,SpeciesHiddenAbility)
       if hiddenAbil.is_a?(Array)
-        ret = hiddenAbil[abilIndex-2]
-        return ret if ret && ret>0
+        ret = hiddenAbil[abilIndex - 2]
+        return ret if ret && ret > 0
       else
-        return hiddenAbil if abilIndex==2 && hiddenAbil>0
+        return hiddenAbil if abilIndex == 2 && hiddenAbil > 0
       end
-      abilIndex = (@personalID&1)
+      abilIndex = (@personalID & 1)
     end
     # Natural ability
     abilities = pbGetSpeciesData(@species,formSimple,SpeciesAbilities)
     if abilities.is_a?(Array)
       ret = abilities[abilIndex]
-      ret = abilities[(abilIndex+1)%2] if !ret || ret==0
+      ret = abilities[(abilIndex + 1) % 2] if !ret || ret == 0
       return ret || 0
     end
     return abilities || 0
   end
 
-  # Returns whether this Pokémon has a particular ability.
-  def hasAbility?(value=0)
-    abil = self.ability
-    return abil>0 if value==0
-    return abil==getID(PBAbilities,value)
+  # Returns whether this Pokémon has a particular ability. If no value
+  # is given, returns whether this Pokémon has an ability set.
+  # @param ability [Integer] ability ID to check  
+  # @return [Boolean] whether this Pokémon has a particular ability or
+  #   an ability at all
+  def hasAbility?(ability = 0)
+    current_ability = self.ability
+    return current_ability > 0 if ability == 0
+    return current_ability == getID(PBAbilities,ability)
   end
 
-  # Sets this Pokémon's ability to a particular ability (if possible).
+  # Sets this Pokémon's ability index.
+  # @param value [Integer] new ability index
   def setAbility(value)
     @abilityflag = value
   end
 
+  # @return [Boolean] whether this Pokémon has a hidden ability
   def hasHiddenAbility?
     abil = abilityIndex
     return abil!=nil && abil>=2
   end
 
-  # Returns the list of abilities this Pokémon can have.
+  # @return [Array<Array<Integer>>] the list of abilities this Pokémon can have
   def getAbilityList
     ret = []
     abilities = pbGetSpeciesData(@species,formSimple,SpeciesAbilities)
@@ -278,26 +311,33 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Nature
   #=============================================================================
-  # Returns the ID of this Pokémon's nature.
+
+  # @return [Integer] the ID of this Pokémon's nature
   def nature
     return @natureflag || (@personalID%25)
   end
 
   # Returns the calculated nature, taking into account things that change its
   # stat-altering effect (i.e. Gen 8 mints). Only used for calculating stats.
+  # @return [Integer] calculated nature
   def calcNature
     return @natureOverride if @natureOverride
     return self.nature
   end
 
-  # Returns whether this Pokémon has a particular nature.
-  def hasNature?(value=-1)
-    nat = self.nature
-    return nat>=0 if value<0
-    return nat==getID(PBNatures,value)
+  # Returns whether this Pokémon has a particular nature. If no value
+  # is given, returns whether this Pokémon has a nature set.
+  # @param nature [Integer] nature ID to check  
+  # @return [Boolean] whether this Pokémon has a particular nature or
+  #   a nature at all
+  def hasNature?(nature = -1)
+    current_nature = self.nature
+    return current_nature >= 0 if nature < 0
+    return current_nature == getID(PBNatures,nature)
   end
 
   # Sets this Pokémon's nature to a particular nature.
+  # @param value [Integer] nature to change to
   def setNature(value)
     @natureflag = getID(PBNatures,value)
     calcStats
@@ -306,14 +346,15 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Shininess
   #=============================================================================
-  # Returns whether this Pokémon is shiny (differently colored).
+
+  # @return [Boolean] whether this Pokémon is shiny (differently colored)
   def shiny?
-    return @shinyflag if @shinyflag!=nil
-    a = @personalID^@trainerID
-    b = a&0xFFFF
-    c = (a>>16)&0xFFFF
-    d = b^c
-    return d<SHINY_POKEMON_CHANCE
+    return @shinyflag if @shinyflag != nil
+    a = @personalID ^ @trainerID
+    b = a & 0xFFFF
+    c = (a >> 16) & 0xFFFF
+    d = b ^ c
+    return d < SHINY_POKEMON_CHANCE
   end
   alias isShiny? shiny?
 
@@ -330,12 +371,15 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Pokérus
   #=============================================================================
-  # Returns the Pokérus infection stage for this Pokémon.
+
+  # @return [Integer] the Pokérus infection stage for this Pokémon
   def pokerusStrain
     return @pokerus/16
   end
 
   # Returns the Pokérus infection stage for this Pokémon.
+  # @return [0, 1, 2] Pokérus infection stage
+  #   (0 = not infected, 1 = cured, 2 = infected)
   def pokerusStage
     return 0 if !@pokerus || @pokerus==0        # Not infected
     return 2 if @pokerus>0 && (@pokerus%16)==0  # Cured
@@ -343,32 +387,34 @@ class PokeBattle_Pokemon
   end
 
   # Gives this Pokémon Pokérus (either the specified strain or a random one).
-  def givePokerus(strain=0)
-    return if self.pokerusStage==2   # Can't re-infect a cured Pokémon
-    strain = 1+rand(15) if strain<=0 || strain>=16
-    time = 1+(strain%4)
+  # @param strain [Integer] Pokérus strain to give
+  def givePokerus(strain = 0)
+    return if self.pokerusStage == 2   # Can't re-infect a cured Pokémon
+    strain = 1 + rand(15) if strain <= 0 || strain >= 16
+    time = 1 + (strain %4 )
     @pokerus = time
     @pokerus |= strain << 4
   end
 
   # Resets the infection time for this Pokémon's Pokérus (even if cured).
   def resetPokerusTime
-    return if @pokerus==0
-    strain = @pokerus%16
-    time = 1+(strain%4)
+    return if @pokerus == 0
+    strain = @pokerus % 16
+    time = 1 + (strain % 4)
     @pokerus = time
     @pokerus |= strain << 4
   end
 
   # Reduces the time remaining for this Pokémon's Pokérus (if infected).
   def lowerPokerusCount
-    return if self.pokerusStage!=1
+    return if self.pokerusStage != 1
     @pokerus -= 1
   end
 
   #=============================================================================
   # Types
   #=============================================================================
+
   # Returns this Pokémon's first type.
   def type1
     return pbGetSpeciesData(@species,formSimple,SpeciesType1)

From 234f435a757589d0b980fe9604f1e71f94410d8b Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Tue, 8 Sep 2020 12:13:47 +0300
Subject: [PATCH 02/11] Additional refactoring, made #mail=(value) into a
 method that checks whether the passed value is valid

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 33 +++++++++++++------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 5404f8d5c..f201d3e7b 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -31,15 +31,20 @@ class PokeBattle_Pokemon
   attr_accessor :genderflag
   # @return [Integer] forces a particular nature (nature ID)
   attr_accessor :natureflag
-  attr_accessor :natureOverride   # Overrides nature's stat-changing effects
-  attr_accessor :shinyflag   # Forces the shininess (true/false)
-  attr_accessor :moves       # Moves (PBMove)
-  attr_accessor :firstmoves  # The moves known when this Pokémon was obtained
-  attr_accessor :item        # Held item
-  attr_writer   :mail        # Mail
-  attr_accessor :fused       # The Pokémon fused into this one
-  attr_accessor :iv          # Array of 6 Individual Values for HP, Atk, Def,
-                             #    Speed, Sp Atk, and Sp Def
+  # @return [Integer] overrides nature's stat-changing effects
+  attr_accessor :natureOverride
+  # @return [Boolean] whether shininess should be forced
+  attr_accessor :shinyflag
+  # @return [Array<PBMove>] moves known by this Pokémon
+  attr_accessor :moves
+  # @return [Array<Integer>] IDs of moves known by this Pokémon when it was obtained
+  attr_accessor :firstmoves
+  # @return [Integer] id of the item held by this Pokémon (0 = no held item)
+  attr_accessor :item
+  # @return [PokeBattle_Pokemon, nil] the Pokémon fused into this one (nil if there is none)
+  attr_accessor :fused
+  # @return [Array<Integer>] array of IV values for HP, Atk, Def, Speed, Sp. Atk and Sp. Def
+  attr_accessor :iv
   attr_writer   :ivMaxed     # Array of booleans that max each IV value
   attr_accessor :ev          # Effort Values
   attr_accessor :happiness   # Current happiness
@@ -663,13 +668,21 @@ class PokeBattle_Pokemon
     return ret
   end
 
-  # Returns this Pokémon's mail.
+  # @return [PokemonMail, nil] mail held by this Pokémon (nil if there is none)
   def mail
     return nil if !@mail
     @mail = nil if @mail.item==0 || !hasItem?(@mail.item)
     return @mail
   end
 
+  # @param mail [PokemonMail, nil] mail to be held by this Pokémon (nil if mail is to be removed)
+  def mail=(mail)
+    if !mail.nil? && !mail.is_a?(PokemonMail)
+      raise ArgumentError, _INTL('Invalid value {1} given',mail.inspect)
+    end
+    @mail = mail
+  end
+
   #=============================================================================
   # Other
   #=============================================================================

From 0faff2b54602dd939bdc0dcd30c3ada5c058581b Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Tue, 8 Sep 2020 12:22:18 +0300
Subject: [PATCH 03/11] fix a typo I made in #givePokerus

---
 Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index f201d3e7b..927ce5ba5 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -274,7 +274,7 @@ class PokeBattle_Pokemon
 
   # Returns whether this Pokémon has a particular ability. If no value
   # is given, returns whether this Pokémon has an ability set.
-  # @param ability [Integer] ability ID to check  
+  # @param ability [Integer] ability ID to check
   # @return [Boolean] whether this Pokémon has a particular ability or
   #   an ability at all
   def hasAbility?(ability = 0)
@@ -332,7 +332,7 @@ class PokeBattle_Pokemon
 
   # Returns whether this Pokémon has a particular nature. If no value
   # is given, returns whether this Pokémon has a nature set.
-  # @param nature [Integer] nature ID to check  
+  # @param nature [Integer] nature ID to check
   # @return [Boolean] whether this Pokémon has a particular nature or
   #   a nature at all
   def hasNature?(nature = -1)
@@ -396,7 +396,7 @@ class PokeBattle_Pokemon
   def givePokerus(strain = 0)
     return if self.pokerusStage == 2   # Can't re-infect a cured Pokémon
     strain = 1 + rand(15) if strain <= 0 || strain >= 16
-    time = 1 + (strain %4 )
+    time = 1 + (strain % 4)
     @pokerus = time
     @pokerus |= strain << 4
   end

From 305cbbb072e43170aebfd2f0d831bfcdc2c94244 Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Tue, 8 Sep 2020 20:02:12 +0300
Subject: [PATCH 04/11] More work on documentation

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 92 +++++++++++++------
 1 file changed, 62 insertions(+), 30 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 927ce5ba5..2cf6e6e60 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -21,19 +21,35 @@ class PokeBattle_Pokemon
   attr_reader   :spatk
   # @return [Integer] current Special Defense stat
   attr_reader   :spdef
-  # @return [Integer] status problem (from PBStatus)
+  # @return [Integer] current status (from PBStatuses)
   attr_accessor :status
+  # Is 0, except if the Pokémon is:
+  #
+  # - Asleep: Is the number of rounds the Pokémon will remain asleep.
+  # This number is set when the Pokémon is made to fall asleep.
+  #
+  # - Badly poisoned: If the Pokémon is Poisoned and this is "1", the
+  # Pokémon is badly poisoned instead (which affects how much poison
+  # damage it takes in battle). When the Pokémon leaves battle while
+  # badly poisoned, this value is set to 0 and it becomes regular Poisoned
+  # (even in later battles).
   # @return [Integer] sleep count / toxic flag
   attr_accessor :statusCount
-  # @return [0, 1, 2] forces the first / second / hidden ability
+  # If defined, forces the Pokémon's ability to be the first natural (0),
+  #   second natural (1) or hidden (2) ability available to its species.
+  #   It is not possible to give the Pokémon any ability other than those
+  #   defined in the PBS file "pokemon.txt" for its species
+  #   (or "pokemonforms.txt" for its species and form). 
+  # @return [0, 1, 2, nil] forced ability index (nil if none is set)
   attr_accessor :abilityflag
-  # @return [0, 1] forces male (0) or female (1)
+  # @return [0, 1, nil] if defined, forces male (0) or female (1)
   attr_accessor :genderflag
   # @return [Integer] forces a particular nature (nature ID)
   attr_accessor :natureflag
   # @return [Integer] overrides nature's stat-changing effects
   attr_accessor :natureOverride
-  # @return [Boolean] whether shininess should be forced
+  # If defined, forces the Pokémon to be shiny (true) or not (false).
+  # @return [Boolean, nil] whether shininess should be forced (nil if undefined)
   attr_accessor :shinyflag
   # @return [Array<PBMove>] moves known by this Pokémon
   attr_accessor :moves
@@ -41,10 +57,13 @@ class PokeBattle_Pokemon
   attr_accessor :firstmoves
   # @return [Integer] id of the item held by this Pokémon (0 = no held item)
   attr_accessor :item
+  # Another Pokémon which has been fused with this Pokémon (or ´nil´ if there is none).
+  #   Currently only used by Kyurem, to record a fused Reshiram or Zekrom.  
   # @return [PokeBattle_Pokemon, nil] the Pokémon fused into this one (nil if there is none)
   attr_accessor :fused
   # @return [Array<Integer>] array of IV values for HP, Atk, Def, Speed, Sp. Atk and Sp. Def
   attr_accessor :iv
+  # @return [Array<Boolean>] 
   attr_writer   :ivMaxed     # Array of booleans that max each IV value
   attr_accessor :ev          # Effort Values
   attr_accessor :happiness   # Current happiness
@@ -420,18 +439,19 @@ class PokeBattle_Pokemon
   # Types
   #=============================================================================
 
-  # Returns this Pokémon's first type.
+  # @return [Integer] this Pokémon's first type
   def type1
     return pbGetSpeciesData(@species,formSimple,SpeciesType1)
   end
 
-  # Returns this Pokémon's second type.
+  # @return [Integer] this Pokémon's second type, or the first type if none is defined
   def type2
     ret = pbGetSpeciesData(@species,formSimple,SpeciesType2)
     ret = pbGetSpeciesData(@species,formSimple,SpeciesType1) if !ret
     return ret
   end
 
+  # @return [Array<Integer>] an array of this Pokémon's types
   def types
     ret1 = pbGetSpeciesData(@species,formSimple,SpeciesType1)
     ret2 = pbGetSpeciesData(@species,formSimple,SpeciesType2)
@@ -440,35 +460,39 @@ class PokeBattle_Pokemon
     return ret
   end
 
-  # Returns whether this Pokémon has the specified type.
+  # @param type [Integer, Symbol, String] type to check (from PBTypes)
+  # @return [Boolean] whether this Pokémon has the specified type
   def hasType?(type)
     t = self.types
     if !type.is_a?(Integer)
       return t.any? { |tp| isConst?(tp,PBTypes,type) }
     end
-    return t.any? { |tp| tp==type }
+    return t.any? { |tp| tp == type }
   end
 
   #=============================================================================
   # Moves
   #=============================================================================
-  # Returns the number of moves known by the Pokémon.
+
+  # @return [Integer] the number of moves known by the Pokémon
   def numMoves
     ret = 0
-    @moves.each { |m| ret += 1 if m && m.id!=0 }
+    @moves.each { |m| ret += 1 if m && m.id != 0 }
     return ret
   end
 
-  # Returns true if the Pokémon knows the given move.
+  # @param move [Integer, Symbol, String] id of the move to check
+  # @return [Boolean] whether the Pokémon knows the given move
   def hasMove?(move)
     move = getID(PBMoves,move)
-    return false if !move || move<=0
-    @moves.each { |m| return true if m && m.id==move }
+    return false if !move || move <= 0
+    @moves.each { |m| return true if m && m.id == move }
     return false
   end
   alias knowsMove? hasMove?
 
   # Returns the list of moves this Pokémon can learn by levelling up.
+  # @return [Array<Array<Integer>>] move list, where every element is [level, move id]
   def getMoveList
     return pbGetSpeciesMoveset(@species,formSimple)
   end
@@ -478,38 +502,39 @@ class PokeBattle_Pokemon
     lvl = self.level
     fullMoveList = self.getMoveList
     moveList = []
-    fullMoveList.each { |m| moveList.push(m[1]) if m[0]<=lvl }
+    fullMoveList.each { |m| moveList.push(m[1]) if m[0] <= lvl }
     moveList = moveList.reverse
     moveList |= []   # Remove duplicates
     moveList = moveList.reverse
-    listend = moveList.length-4
-    listend = 0 if listend<0
+    listend = moveList.length - 4
+    listend = 0 if listend < 0
     j = 0
     for i in listend...listend+4
-      moveid = (i>=moveList.length) ? 0 : moveList[i]
+      moveid = (i >= moveList.length) ? 0 : moveList[i]
       @moves[j] = PBMove.new(moveid)
       j += 1
     end
   end
 
   # Silently learns the given move. Will erase the first known move if it has to.
+  # @param move [Integer, Symbol, String] id of the move to learn
   def pbLearnMove(move)
     move = getID(PBMoves,move)
-    return if move<=0
+    return if move <= 0
     for i in 0...4   # Already knows move, relocate it to the end of the list
-      next if @moves[i].id!=move
-      j = i+1
-      while j<4
-        break if @moves[j].id==0
+      next if @moves[i].id != move
+      j = i + 1
+      while j < 4
+        break if @moves[j].id == 0
         tmp = @moves[j]
-        @moves[j] = @moves[j-1]
-        @moves[j-1] = tmp
+        @moves[j] = @moves[j - 1]
+        @moves[j - 1] = tmp
         j += 1
       end
       return
     end
     for i in 0...4   # Has empty move slot, put move in there
-      next if @moves[i].id!=0
+      next if @moves[i].id != 0
       @moves[i] = PBMove.new(move)
       return
     end
@@ -521,11 +546,12 @@ class PokeBattle_Pokemon
   end
 
   # Deletes the given move from the Pokémon.
+  # @param move [Integer, Symbol, String] id of the move to delete
   def pbDeleteMove(move)
     move = getID(PBMoves,move)
     return if !move || move<=0
     newMoves = []
-    @moves.each { |m| newMoves.push(m) if m && m.id!=move }
+    @moves.each { |m| newMoves.push(m) if m && m.id != move }
     newMoves.push(PBMove.new(0))
     for i in 0...4
       @moves[i] = newMoves[i]
@@ -533,9 +559,10 @@ class PokeBattle_Pokemon
   end
 
   # Deletes the move at the given index from the Pokémon.
+  # @param index [Integer] index of the move to be deleted
   def pbDeleteMoveAtIndex(index)
     newMoves = []
-    @moves.each_with_index { |m,i| newMoves.push(m) if m && i!=index }
+    @moves.each_with_index { |m,i| newMoves.push(m) if m && i != index }
     newMoves.push(PBMove.new(0))
     for i in 0...4
       @moves[i] = newMoves[i]
@@ -552,23 +579,28 @@ class PokeBattle_Pokemon
   # Copies currently known moves into a separate array, for Move Relearner.
   def pbRecordFirstMoves
     @firstmoves = []
-    @moves.each { |m| @firstmoves.push(m.id) if m && m.id>0 }
+    @moves.each { |m| @firstmoves.push(m.id) if m && m.id > 0 }
   end
 
+  # TODO Figure out better documentation for these first move methods
+  # @param move [Integer, Symbol, String] id of the move to add
   def pbAddFirstMove(move)
     move = getID(PBMoves,move)
-    @firstmoves.push(move) if move>0 && !@firstmoves.include?(move)
+    @firstmoves.push(move) if move > 0 && !@firstmoves.include?(move)
   end
 
+  # @param move [Integer, Symbol, String] id of the move to remove
   def pbRemoveFirstMove(move)
     move = getID(PBMoves,move)
-    @firstmoves.delete(move) if move>0
+    @firstmoves.delete(move) if move > 0
   end
 
   def pbClearFirstMoves
     @firstmoves = []
   end
 
+  # @param move [Integer, Symbol, String] id of the move to check
+  # @return [Boolean] whether the Pokémon is compatible with the move
   def compatibleWithMove?(move)
     return pbSpeciesCompatible?(self.fSpecies,move)
   end

From 39e38cc74f17636c0eedbe1c286bf84e8f7e2a05 Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Sun, 13 Sep 2020 13:34:44 +0300
Subject: [PATCH 05/11] Added documentation to most of PokeBattle_Pokemon

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 133 +++++++++++-------
 1 file changed, 83 insertions(+), 50 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 2cf6e6e60..234b2e4c4 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -403,11 +403,11 @@ class PokeBattle_Pokemon
 
   # Returns the Pokérus infection stage for this Pokémon.
   # @return [0, 1, 2] Pokérus infection stage
-  #   (0 = not infected, 1 = cured, 2 = infected)
+  #   (0 = not infected, 1 = infected, 2 = cured)
   def pokerusStage
-    return 0 if !@pokerus || @pokerus==0        # Not infected
-    return 2 if @pokerus>0 && (@pokerus%16)==0  # Cured
-    return 1                                    # Infected
+    return 0 if !@pokerus || @pokerus==0
+    return 2 if @pokerus > 0 && (@pokerus % 16) == 0
+    return 1
   end
 
   # Gives this Pokémon Pokérus (either the specified strain or a random one).
@@ -595,6 +595,7 @@ class PokeBattle_Pokemon
     @firstmoves.delete(move) if move > 0
   end
 
+  # Clears this Pokémon's first moves.
   def pbClearFirstMoves
     @firstmoves = []
   end
@@ -608,34 +609,48 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Contest attributes, ribbons
   #=============================================================================
-  def cool;   return @cool || 0;   end
-  def beauty; return @beauty || 0; end
-  def cute;   return @cute || 0;   end
-  def smart;  return @smart || 0;  end
-  def tough;  return @tough || 0;  end
-  def sheen;  return @sheen || 0;  end
 
-  # Returns the number of ribbons this Pokémon has.
+  # @return [Integer] this Pokémon's cool contest attribute
+  def cool; return @cool || 0; end
+
+  # @return [Integer] this Pokémon's beauty contest attribute
+  def beauty; return @beauty || 0; end
+
+  # @return [Integer] this Pokémon's cute contest attribute
+  def cute; return @cute || 0; end
+
+  # @return [Integer] this Pokémon's smart contest attribute
+  def smart; return @smart || 0; end
+
+  # @return [Integer] this Pokémon's tough contest attribute
+  def tough; return @tough || 0; end
+
+  # @return [Integer] this Pokémon's sheen contest attribute
+  def sheen; return @sheen || 0; end
+  
+  # @return [Integer] the number of ribbons this Pokémon has
   def ribbonCount
     return (@ribbons) ? @ribbons.length : 0
   end
 
-  # Returns whether this Pokémon has the specified ribbon.
+  # @param ribbon [Integer, Symbol, String] ribbon id to check
+  # @return [Boolean] whether this Pokémon has the specified ribbon
   def hasRibbon?(ribbon)
     return false if !@ribbons
     ribbon = getID(PBRibbons,ribbon)
-    return false if ribbon==0
+    return false if ribbon == 0
     return @ribbons.include?(ribbon)
   end
 
-  # Gives this Pokémon the specified ribbon.
+  # @param ribbon [Integer, Symbol, String] id of the ribbon to give
   def giveRibbon(ribbon)
     @ribbons = [] if !@ribbons
     ribbon = getID(PBRibbons,ribbon)
-    return if ribbon==0
+    return if ribbon == 0
     @ribbons.push(ribbon) if !@ribbons.include?(ribbon)
   end
 
+  # TODO Figure out a good way to document this
   # Replaces one ribbon with the next one along, if possible.
   def upgradeRibbon(*arg)
     @ribbons = [] if !@ribbons
@@ -657,7 +672,7 @@ class PokeBattle_Pokemon
     return 0
   end
 
-  # Removes the specified ribbon from this Pokémon.
+  # @param ribbon [Integer, Symbol, String] id of the ribbon to remove
   def takeRibbon(ribbon)
     return if !@ribbons
     ribbon = getID(PBRibbons,ribbon)
@@ -678,20 +693,24 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Items
   #=============================================================================
+
   # Returns whether this Pokémon is holding an item. If an item id is passed,
   # returns whether the Pokémon is holding that item.
+  # @param item_id [Integer, Symbol, String] id of the item to check
+  # @return [Boolean] whether the Pokémon is holding the specified item or
+  #   an item at all
   def hasItem?(item_id = 0)
     held_item = self.item
     return held_item > 0 if item_id == 0
     return held_item == getID(PBItems,item_id)
   end
 
-  # Sets this Pokémon's item. Accepts symbols.
-  def setItem(value)
-    self.item = getID(PBItems,value)
+  # @param item_id [Integer, Symbol, String] id of the item to give to this Pokémon
+  def setItem(item_id)
+    self.item = getID(PBItems,item_id)
   end
 
-  # Returns the items this species can be found holding in the wild.
+  # @return [Array<Integer>] the items this species can be found holding in the wild
   def wildHoldItems
     ret = []
     ret.push(pbGetSpeciesData(@species,formSimple,SpeciesWildItemCommon))
@@ -703,7 +722,7 @@ class PokeBattle_Pokemon
   # @return [PokemonMail, nil] mail held by this Pokémon (nil if there is none)
   def mail
     return nil if !@mail
-    @mail = nil if @mail.item==0 || !hasItem?(@mail.item)
+    @mail = nil if @mail.item == 0 || !hasItem?(@mail.item)
     return @mail
   end
 
@@ -718,40 +737,47 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Other
   #=============================================================================
-  def species=(value)
+
+  # Changes the Pokémon's species and re-calculates its statistics.
+  # @param species_id [Integer] id of the species to change this Pokémon to
+  def species=(species_id)
     hasNickname = nicknamed?
-    @species    = value
+    @species    = species_id
     @name       = PBSpecies.getName(@species) unless hasNickname
     @level      = nil   # In case growth rate is different for the new species
     @forcedForm = nil
     calcStats
   end
 
-  def isSpecies?(s)
-    s = getID(PBSpecies,s)
-    return s && @species==s
+  # @param species [Integer, Symbol, String] id of the species to check for
+  # @return [Boolean] whether this Pokémon is of the specified species
+  def isSpecies?(species)
+    species = getID(PBSpecies,species)
+    return species && @species == species
   end
 
-  # Returns the species name of this Pokémon.
+  # @return [String] the species name of this Pokémon
   def speciesName
     return PBSpecies.getName(@species)
   end
 
+  # @return [Boolean] whether this Pokémon has been nicknamed
   def nicknamed?
-    return @name!=self.speciesName
+    return @name != self.speciesName
   end
 
-  # Returns this Pokémon's language.
+  # @return [Integer] this Pokémon's language
   def language; return @language || 0; end
 
-  # Returns the markings this Pokémon has.
+  # @return [Integer] the markings this Pokémon has
   def markings; return @markings || 0; end
 
-  # Returns a string stating the Unown form of this Pokémon.
+  # @return [String] a string stating the Unown form of this Pokémon
   def unownShape
     return "ABCDEFGHIJKLMNOPQRSTUVWXYZ?!"[@form,1]
   end
 
+  # TODO Check whether #height and #weight always return an integer
   # Returns the height of this Pokémon.
   def height
     return pbGetSpeciesData(@species,formSimple,SpeciesHeight)
@@ -786,19 +812,21 @@ class PokeBattle_Pokemon
 
   # Sets this Pokémon's HP.
   def hp=(value)
-    value = 0 if value<0
+    value = 0 if value < 0
     @hp = value
-    if @hp==0
+    if @hp == 0
       @status      = PBStatuses::NONE
       @statusCount = 0
     end
   end
 
+  # @return [Boolean] whether the Pokémon is not fainted and not an egg
   def able?
     return !egg? && @hp>0
   end
   alias isAble? able?
 
+  # @return [Boolean] whether the Pokémon is fainted
   def fainted?
     return !egg? && @hp<=0
   end
@@ -817,11 +845,14 @@ class PokeBattle_Pokemon
     @statusCount = 0
   end
 
-  # Heals all PP of this Pokémon.
-  def healPP(index=-1)
+  # Heals all PP of this Pokémon. If a move index is given, heals the PP
+  # of the move in that index.
+  # @param move_index [Integer] index of the move to heal (-1 if all moves
+  #   should be healed)
+  def healPP(move_index = -1)
     return if egg?
-    if index>=0
-      @moves[index].pp = @moves[index].totalpp
+    if move_index >= 0
+      @moves[move_index].pp = @moves[move_index].totalpp
     else
       @moves.each { |m| m.pp = m.totalpp }
     end
@@ -836,6 +867,7 @@ class PokeBattle_Pokemon
   end
 
   # Changes the happiness of this Pokémon depending on what happened to change it.
+  # @param method [String] the happiness changing method (e.g. 'walking')
   def changeHappiness(method)
     gain = 0
     case method
@@ -896,19 +928,20 @@ class PokeBattle_Pokemon
   #=============================================================================
   # Stat calculations, Pokémon creation
   #=============================================================================
-  # Returns this Pokémon's base stats. An array of six values.
+
+  # @return [Array<Integer>] this Pokémon's base stats, an array of six values
   def baseStats
     ret = pbGetSpeciesData(@species,formSimple,SpeciesBaseStats)
     return ret.clone
   end
 
-  # Returns the maximum HP of this Pokémon.
+  # @return [Integer] the maximum HP of this Pokémon
   def calcHP(base,level,iv,ev)
-    return 1 if base==1   # For Shedinja
-    return ((base*2+iv+(ev>>2))*level/100).floor+level+10
+    return 1 if base == 1   # For Shedinja
+    return ((base * 2 + iv + (ev >> 2)) * level / 100).floor + level + 10
   end
 
-  # Returns the specified stat of this Pokémon (not used for total HP).
+  # @return [Integer] the specified stat of this Pokémon (not used for total HP)
   def calcStat(base,level,iv,ev,pv)
     return ((((base*2+iv+(ev>>2))*level/100).floor+5)*pv/100).floor
   end
@@ -939,6 +972,7 @@ class PokeBattle_Pokemon
     @speed   = stats[PBStats::SPEED]
   end
 
+  # @return [PokeBattle_Pokemon] a copy of this Pokémon
   def clone
     ret = super
     ret.iv      = @iv.clone
@@ -951,16 +985,16 @@ class PokeBattle_Pokemon
   end
 
   # Creates a new Pokémon object.
-  #    species   - Pokémon species.
-  #    level     - Pokémon level.
-  #    player    - PokeBattle_Trainer object for the original trainer.
-  #    withMoves - If false, this Pokémon has no moves.
+  # @param species [Integer, Symbol, String] Pokémon species
+  # @param level [Integer] Pokémon level
+  # @param player [PokeBattle_Trainer] object for the original trainer
+  # @param withMoves [Boolean] whether the Pokémon should have moves
   def initialize(species,level,player=nil,withMoves=true)
     ospecies = species.to_s
     species = getID(PBSpecies,species)
     cname = getConstantName(PBSpecies,species) rescue nil
-    realSpecies = pbGetSpeciesFromFSpecies(species)[0] if species && species>0
-    if !species || species<=0 || realSpecies>PBSpecies.maxValue || !cname
+    realSpecies = pbGetSpeciesFromFSpecies(species)[0] if species && species > 0
+    if !species || species<=0 || realSpecies > PBSpecies.maxValue || !cname
       raise ArgumentError.new(_INTL("The species given ({1}) is invalid.",ospecies))
     end
     @species      = realSpecies
@@ -1018,8 +1052,7 @@ class PokeBattle_Pokemon
   end
 end
 
-
-
+# (see PokeBattle_Pokemon#initialize)
 def pbNewPkmn(species,level,owner=nil,withMoves=true)
   owner = $Trainer if !owner
   return PokeBattle_Pokemon.new(species,level,owner,withMoves)

From d6e9ff6acbc932f9b2ebbefced0388dc082ee257 Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Fri, 18 Sep 2020 13:56:24 +0300
Subject: [PATCH 06/11] Moved methods related to status into a new section
 Also, added more documentation

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 163 +++++++++++-------
 1 file changed, 99 insertions(+), 64 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 234b2e4c4..4559a6a8a 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -21,20 +21,6 @@ class PokeBattle_Pokemon
   attr_reader   :spatk
   # @return [Integer] current Special Defense stat
   attr_reader   :spdef
-  # @return [Integer] current status (from PBStatuses)
-  attr_accessor :status
-  # Is 0, except if the Pokémon is:
-  #
-  # - Asleep: Is the number of rounds the Pokémon will remain asleep.
-  # This number is set when the Pokémon is made to fall asleep.
-  #
-  # - Badly poisoned: If the Pokémon is Poisoned and this is "1", the
-  # Pokémon is badly poisoned instead (which affects how much poison
-  # damage it takes in battle). When the Pokémon leaves battle while
-  # badly poisoned, this value is set to 0 and it becomes regular Poisoned
-  # (even in later battles).
-  # @return [Integer] sleep count / toxic flag
-  attr_accessor :statusCount
   # If defined, forces the Pokémon's ability to be the first natural (0),
   #   second natural (1) or hidden (2) ability available to its species.
   #   It is not possible to give the Pokémon any ability other than those
@@ -160,7 +146,7 @@ class PokeBattle_Pokemon
   # Sets this Pokémon's level.
   # @param value [Integer] new level (between 1 and the maximum level)
   def level=(value)
-    if value<1 || value>PBExperience.maxLevel
+    if value < 1 || value > PBExperience.maxLevel
       raise ArgumentError.new(_INTL("The level number ({1}) is invalid.",value))
     end
     @level = value
@@ -734,6 +720,94 @@ class PokeBattle_Pokemon
     @mail = mail
   end
 
+  #=============================================================================
+  # Status
+  #=============================================================================
+
+  # @return [Integer] current status (from PBStatuses)
+  def status
+    return @status
+  end
+
+  # @param new_status [Integer, Symbol, String] status to set (from PBStatuses)
+  def status=(new_status)
+    if new_status.is_a?(Integer)
+      @status = new_status
+    else
+      if !new_status.is_a?(Symbol) && !new_status.is_a?(String)
+        raise ArgumentError, _INTL('Attempted to set a {1} as Pokémon status',new_status.class.name)
+      end
+      @status = getID(PBStatuses,new_status)
+    end
+  end
+
+  # Is 0, except if the Pokémon is:
+  #
+  # - Asleep: Is the number of rounds the Pokémon will remain asleep.
+  # This number is set when the Pokémon is made to fall asleep.
+  #
+  # - Badly poisoned: If the Pokémon is Poisoned and this is "1", the
+  # Pokémon is badly poisoned instead (which affects how much poison
+  # damage it takes in battle). When the Pokémon leaves battle while
+  # badly poisoned, this value is set to 0 and it becomes regular Poisoned
+  # (even in later battles).
+  # @return [Integer] sleep count / toxic flag
+  def statusCount
+    return @statusCount
+  end
+
+  # (see #statusCount)
+  # @param new_status_count [Integer] new sleep count / toxic flag
+  def statusCount=(new_status_count)
+    @statusCount = new_status_count
+  end
+
+  # @return [Boolean] whether the Pokémon is not fainted and not an egg
+  def able?
+    return !egg? && @hp > 0
+  end
+  alias isAble? able?
+  
+  # @return [Boolean] whether the Pokémon is fainted
+  def fainted?
+    return !egg? && @hp <= 0
+  end
+  alias isFainted? fainted?
+  
+  # Heals all HP of this Pokémon.
+  def healHP
+    return if egg?
+    @hp = @totalhp
+  end
+  
+  # Heals the status problem of this Pokémon.
+  def healStatus
+    return if egg?
+    @status      = PBStatuses::NONE
+    @statusCount = 0
+  end
+  
+  # Heals all PP of this Pokémon. If a move index is given, heals the PP
+  # of the move in that index.
+  # @param move_index [Integer] index of the move to heal (-1 if all moves
+  #   should be healed)
+  def healPP(move_index = -1)
+    return if egg?
+    if move_index >= 0
+      @moves[move_index].pp = @moves[move_index].totalpp
+    else
+      @moves.each { |m| m.pp = m.totalpp }
+    end
+  end
+  
+  # Heals all HP, PP, and status problems of this Pokémon.
+  def heal
+    return if egg?
+    healHP
+    healStatus
+    healPP
+  end
+
   #=============================================================================
   # Other
   #=============================================================================
@@ -790,12 +864,14 @@ class PokeBattle_Pokemon
 
   # Returns an array of booleans indicating whether a stat is made to have
   # maximum IVs (for Hyper Training). Set like @ivMaxed[PBStats::ATTACK] = true
+  # @return [Array<Boolean>] array indicating whether a stat has maximum IVs
   def ivMaxed
     return @ivMaxed || []
   end
 
   # Returns this Pokémon's effective IVs, taking into account Hyper Training.
   # Only used for calculating stats.
+  # @return [Array<Boolean>] array containing this Pokémon's effective IVs
   def calcIV
     ret = self.iv.clone
     if @ivMaxed
@@ -804,13 +880,14 @@ class PokeBattle_Pokemon
     return ret
   end
 
-  # Returns the EV yield of this Pokémon.
+  # @return [Array<Integer>] the EV yield of this Pokémon (an array of six values)
   def evYield
     ret = pbGetSpeciesData(@species,formSimple,SpeciesEffortPoints)
     return ret.clone
   end
 
-  # Sets this Pokémon's HP.
+  # Sets the Pokémon's health.
+  # @param value [Integer] new hp value
   def hp=(value)
     value = 0 if value < 0
     @hp = value
@@ -820,52 +897,6 @@ class PokeBattle_Pokemon
     end
   end
 
-  # @return [Boolean] whether the Pokémon is not fainted and not an egg
-  def able?
-    return !egg? && @hp>0
-  end
-  alias isAble? able?
-
-  # @return [Boolean] whether the Pokémon is fainted
-  def fainted?
-    return !egg? && @hp<=0
-  end
-  alias isFainted? fainted?
-
-  # Heals all HP of this Pokémon.
-  def healHP
-    return if egg?
-    @hp = @totalhp
-  end
-
-  # Heals the status problem of this Pokémon.
-  def healStatus
-    return if egg?
-    @status      = PBStatuses::NONE
-    @statusCount = 0
-  end
-
-  # Heals all PP of this Pokémon. If a move index is given, heals the PP
-  # of the move in that index.
-  # @param move_index [Integer] index of the move to heal (-1 if all moves
-  #   should be healed)
-  def healPP(move_index = -1)
-    return if egg?
-    if move_index >= 0
-      @moves[move_index].pp = @moves[move_index].totalpp
-    else
-      @moves.each { |m| m.pp = m.totalpp }
-    end
-  end
-
-  # Heals all HP, PP, and status problems of this Pokémon.
-  def heal
-    return if egg?
-    healHP
-    healStatus
-    healPP
-  end
-
   # Changes the happiness of this Pokémon depending on what happened to change it.
   # @param method [String] the happiness changing method (e.g. 'walking')
   def changeHappiness(method)
@@ -1052,7 +1083,11 @@ class PokeBattle_Pokemon
   end
 end
 
-# (see PokeBattle_Pokemon#initialize)
+# Creates a new Pokémon object.
+# @param species [Integer, Symbol, String] Pokémon species
+# @param level [Integer] Pokémon level
+# @param owner [PokeBattle_Trainer] object for the original trainer
+# @param withMoves [Boolean] whether the Pokémon should have moves
 def pbNewPkmn(species,level,owner=nil,withMoves=true)
   owner = $Trainer if !owner
   return PokeBattle_Pokemon.new(species,level,owner,withMoves)

From 07604a3f6164ea74d5e3e62ab4c90242b7654234 Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Fri, 18 Sep 2020 14:34:26 +0300
Subject: [PATCH 07/11] More documentation, fixed bad YARD formatting

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 28 +++++++++++--------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 4559a6a8a..70a8a2f35 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -22,10 +22,10 @@ class PokeBattle_Pokemon
   # @return [Integer] current Special Defense stat
   attr_reader   :spdef
   # If defined, forces the Pokémon's ability to be the first natural (0),
-  #   second natural (1) or hidden (2) ability available to its species.
-  #   It is not possible to give the Pokémon any ability other than those
-  #   defined in the PBS file "pokemon.txt" for its species
-  #   (or "pokemonforms.txt" for its species and form). 
+  # second natural (1) or hidden (2) ability available to its species.
+  # It is not possible to give the Pokémon any ability other than those
+  # defined in the PBS file "pokemon.txt" for its species
+  # (or "pokemonforms.txt" for its species and form). 
   # @return [0, 1, 2, nil] forced ability index (nil if none is set)
   attr_accessor :abilityflag
   # @return [0, 1, nil] if defined, forces male (0) or female (1)
@@ -43,17 +43,20 @@ class PokeBattle_Pokemon
   attr_accessor :firstmoves
   # @return [Integer] id of the item held by this Pokémon (0 = no held item)
   attr_accessor :item
-  # Another Pokémon which has been fused with this Pokémon (or ´nil´ if there is none).
-  #   Currently only used by Kyurem, to record a fused Reshiram or Zekrom.  
+  # Another Pokémon which has been fused with this Pokémon (or nil if there is none).
+  # Currently only used by Kyurem, to record a fused Reshiram or Zekrom.  
   # @return [PokeBattle_Pokemon, nil] the Pokémon fused into this one (nil if there is none)
   attr_accessor :fused
   # @return [Array<Integer>] array of IV values for HP, Atk, Def, Speed, Sp. Atk and Sp. Def
   attr_accessor :iv
-  # @return [Array<Boolean>] 
-  attr_writer   :ivMaxed     # Array of booleans that max each IV value
-  attr_accessor :ev          # Effort Values
+  # @param value [Array<Boolean>] array of booleans that max each IV value
+  attr_writer   :ivMaxed
+  # @return [Array<Integer>] this Pokémon's effort values
+  attr_accessor :ev
+  # @return [Integer] this Pokémon's current happiness (an integer between 0 and 255)
   attr_accessor :happiness   # Current happiness
-  attr_accessor :ballused    # Ball used
+  # @return [Integer] the type of ball used (refer to {$BallTypes} for valid types)
+  attr_accessor :ballused
   attr_accessor :eggsteps    # Steps to hatch egg, 0 if Pokémon is not an egg
   attr_writer   :markings    # Markings
   attr_accessor :ribbons     # Array of ribbons
@@ -724,11 +727,14 @@ class PokeBattle_Pokemon
   # Status
   #=============================================================================
 
+  # Returns the current status of this Pokémon. See {PBStatuses} for all possible
+  # status effects.
   # @return [Integer] current status (from PBStatuses)
   def status
     return @status
   end
 
+  # Sets this Pokémon's status. See {PBStatuses} for all possible status effects.
   # @param new_status [Integer, Symbol, String] status to set (from PBStatuses)
   def status=(new_status)
     if new_status.is_a?(Integer)
@@ -756,7 +762,7 @@ class PokeBattle_Pokemon
     return @statusCount
   end
 
-  # (see #statusCount)
+  # Sets a new status count. See {#statusCount} for more information.
   # @param new_status_count [Integer] new sleep count / toxic flag
   def statusCount=(new_status_count)
     @statusCount = new_status_count

From 1d698a6a44af170320af891cb2a4c1c27ed73b2e Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Fri, 18 Sep 2020 20:12:35 +0300
Subject: [PATCH 08/11] Documented the rest of PokeBattle_Pokemon

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 193 ++++++++++--------
 1 file changed, 111 insertions(+), 82 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 70a8a2f35..77e84551b 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -1,25 +1,25 @@
 # This class stores data on each Pokémon. Refer to $Trainer.party for an array
 # of each Pokémon in the Trainer's current party.
 class PokeBattle_Pokemon
-  # @return [String] nickname
+  # @return [String] the nickname
   attr_accessor :name
-  # @return [Integer] national Pokédex number
+  # @return [Integer] the national Pokédex number
   attr_reader   :species
-  # @return [Integer] current experience points
+  # @return [Integer] the current experience points
   attr_reader   :exp
-  # @return [Integer] current HP
+  # @return [Integer] the current HP
   attr_reader   :hp
-  # @return [Integer] current Total HP
+  # @return [Integer] the current Total HP
   attr_reader   :totalhp
-  # @return [Integer] current Attack stat
+  # @return [Integer] the current Attack stat
   attr_reader   :attack
-  # @return [Integer] current Defense stat
+  # @return [Integer] the current Defense stat
   attr_reader   :defense
-  # @return [Integer] current Speed stat
+  # @return [Integer] the current Speed stat
   attr_reader   :speed
-  # @return [Integer] current Special Attack stat
+  # @return [Integer] the current Special Attack stat
   attr_reader   :spatk
-  # @return [Integer] current Special Defense stat
+  # @return [Integer] the current Special Defense stat
   attr_reader   :spdef
   # If defined, forces the Pokémon's ability to be the first natural (0),
   # second natural (1) or hidden (2) ability available to its species.
@@ -28,79 +28,105 @@ class PokeBattle_Pokemon
   # (or "pokemonforms.txt" for its species and form). 
   # @return [0, 1, 2, nil] forced ability index (nil if none is set)
   attr_accessor :abilityflag
-  # @return [0, 1, nil] if defined, forces male (0) or female (1)
+  # If defined, forces this Pokémon to be male (0) or female (1).
+  # @return [0, 1, nil] gender to force: male (0) or female (1) (nil if undefined)
   attr_accessor :genderflag
-  # @return [Integer] forces a particular nature (nature ID)
+  # If defined, forces this Pokémon to have a particular nature.
+  # @return [Integer, nil] ID of the nature to force (nil if undefined)
   attr_accessor :natureflag
-  # @return [Integer] overrides nature's stat-changing effects
+  # If defined, overrides this Pokémon's nature's stat-changing effects.
+  # @return [Integer, nil] overridden nature stat-changing effects (nil if undefined)
   attr_accessor :natureOverride
   # If defined, forces the Pokémon to be shiny (true) or not (false).
   # @return [Boolean, nil] whether shininess should be forced (nil if undefined)
   attr_accessor :shinyflag
-  # @return [Array<PBMove>] moves known by this Pokémon
+  # @return [Array<PBMove>] the moves known by this Pokémon
   attr_accessor :moves
-  # @return [Array<Integer>] IDs of moves known by this Pokémon when it was obtained
+  # @return [Array<Integer>] the IDs of moves known by this Pokémon when it was obtained
   attr_accessor :firstmoves
-  # @return [Integer] id of the item held by this Pokémon (0 = no held item)
+  # @return [Integer] the ID of the item held by this Pokémon (0 = no held item)
   attr_accessor :item
   # Another Pokémon which has been fused with this Pokémon (or nil if there is none).
   # Currently only used by Kyurem, to record a fused Reshiram or Zekrom.  
   # @return [PokeBattle_Pokemon, nil] the Pokémon fused into this one (nil if there is none)
   attr_accessor :fused
-  # @return [Array<Integer>] array of IV values for HP, Atk, Def, Speed, Sp. Atk and Sp. Def
+  # @return [Array<Integer>] an array of IV values for HP, Atk, Def, Speed, Sp. Atk and Sp. Def
   attr_accessor :iv
-  # @param value [Array<Boolean>] array of booleans that max each IV value
+  # @param value [Array<Boolean>] an array of booleans that max each IV value
   attr_writer   :ivMaxed
   # @return [Array<Integer>] this Pokémon's effort values
   attr_accessor :ev
   # @return [Integer] this Pokémon's current happiness (an integer between 0 and 255)
-  attr_accessor :happiness   # Current happiness
+  attr_accessor :happiness
   # @return [Integer] the type of ball used (refer to {$BallTypes} for valid types)
   attr_accessor :ballused
-  attr_accessor :eggsteps    # Steps to hatch egg, 0 if Pokémon is not an egg
-  attr_writer   :markings    # Markings
-  attr_accessor :ribbons     # Array of ribbons
-  attr_accessor :pokerus     # Pokérus strain and infection time
-  attr_accessor :personalID  # Personal ID
-  attr_accessor :trainerID   # 32-bit Trainer ID (the secret ID is in the upper
-                             #    16 bits)
-  attr_accessor :obtainMode  # Manner obtained:
-                             #    0 - met, 1 - as egg, 2 - traded,
-                             #    4 - fateful encounter
-  attr_accessor :obtainMap   # Map where obtained
-  attr_accessor :obtainText  # Replaces the obtain map's name if not nil
-  attr_writer   :obtainLevel # Level obtained
-  attr_accessor :hatchedMap  # Map where an egg was hatched
-  attr_writer   :language    # Language
-  attr_accessor :ot          # Original Trainer's name
-  attr_writer   :otgender    # Original Trainer's gender:
-                             #    0 - male, 1 - female, 2 - mixed, 3 - unknown
-                             #    For information only, not used to verify
-                             #    ownership of the Pokémon
-  attr_writer   :cool,:beauty,:cute,:smart,:tough,:sheen   # Contest stats
+  # @return [Integer] the number of steps until the egg hatches, 0 if Pokémon is not an egg
+  attr_accessor :eggsteps
+  # @param value [Integer] new markings for this Pokémon
+  attr_writer   :markings
+  # @return [Array<Integer>] an array of ribbons owned by this Pokémon
+  attr_accessor :ribbons
+  # @return [Integer] the Pokérus strain and infection time
+  attr_accessor :pokerus
+  # @return [Integer] this Pokémon's personal ID
+  attr_accessor :personalID
+  # The 32-bit ID of this Pokémon's trainer. The secret ID is in the
+  # upper 16 bits.
+  # @return [Integer] the ID of this Pokémon's trainer
+  attr_accessor :trainerID
+  # @return [Integer] the manner this Pokémon was obtained:
+  #   0 (met), 1 (as egg), 2 (traded), 4 (fateful encounter)
+  attr_accessor :obtainMode
+  # @return [Integer] the ID of the map this Pokémon was obtained in
+  attr_accessor :obtainMap
+  # Describes the manner this Pokémon was obtained. If left undefined,
+  # the obtain map's name is used.
+  # @return [String] the obtain text
+  attr_accessor :obtainText
+  # @param value [Integer] new obtain level
+  attr_writer   :obtainLevel
+  # If this Pokémon hatched from an egg, returns the map ID where the hatching happened.
+  # Otherwise returns 0.
+  # @return [Integer] the map ID where egg was hatched (0 by default)
+  attr_accessor :hatchedMap
+  # @param value [Integer] new language 
+  attr_writer   :language
+  # @return [String] the name of the original trainer
+  attr_accessor :ot
+  # Changes the gender of the original trainer. This is for information only,
+  # and is not used to verify ownership of the Pokémon.
+  # @param value [Integer] new value for the original trainer's gender:
+  #   0 - male, 1 - female, 2 - mixed, 3 - unknown
+  attr_writer   :otgender
+  # @param value [Integer] new contest stat
+  attr_writer   :cool,:beauty,:cute,:smart,:tough,:sheen
 
-  IV_STAT_LIMIT         = 31    # Max total IVs
-  EV_LIMIT              = 510   # Max total EVs
-  EV_STAT_LIMIT         = 252   # Max EVs that a single stat can have
-  MAX_POKEMON_NAME_SIZE = 10    # Maximum length a Pokémon's nickname can be
+  # Max total IVs
+  IV_STAT_LIMIT         = 31
+  # Max total EVs
+  EV_LIMIT              = 510
+  # Max EVs that a single stat can have
+  EV_STAT_LIMIT         = 252
+  # Maximum length a Pokémon's nickname can be
+  MAX_POKEMON_NAME_SIZE = 10
 
   #=============================================================================
   # Ownership, obtained information
   #=============================================================================
 
-  # @return [Integer] public portion of the original trainer's ID
+  # @return [Integer] the public portion of the original trainer's ID
   def publicID
     return @trainerID & 0xFFFF
   end
 
   # @param trainer [PokeBattle_Trainer] the trainer to compare to the OT
-  # @return [Boolean] whether the trainer and OT don't match
+  # @return [Boolean] whether the given trainer and this Pokémon's original trainer don't match
   def foreign?(trainer)
     return @trainerID != trainer.id || @ot != trainer.name
   end
   alias isForeign? foreign?
 
-  # @return [0, 1, 2] gender of this Pokémon original trainer (0 = male, 1 = female, 2 = unknown)
+  # @return [0, 1, 2] the gender of this Pokémon original trainer (0 = male, 1 = female, 2 = unknown)
   def otgender
     return @otgender || 2
   end
@@ -110,7 +136,7 @@ class PokeBattle_Pokemon
     return @obtainLevel || 0
   end
 
-  # @return [Time] time when this Pokémon was obtained
+  # @return [Time] the time when this Pokémon was obtained
   def timeReceived
     return @timeReceived ? Time.at(@timeReceived) : Time.gm(2000)
   end
@@ -121,7 +147,7 @@ class PokeBattle_Pokemon
     @timeReceived = value.to_i
   end
 
-  # @return [Time] time when this Pokémon hatched
+  # @return [Time] the time when this Pokémon hatched
   def timeEggHatched
     if obtainMode==1
       return @timeEggHatched ? Time.at(@timeEggHatched) : Time.gm(2000)
@@ -146,7 +172,8 @@ class PokeBattle_Pokemon
     return @level
   end
 
-  # Sets this Pokémon's level.
+  # Sets this Pokémon's level. The given level must be between 1 and the
+  # maximum level (defined in {PBExperience}).
   # @param value [Integer] new level (between 1 and the maximum level)
   def level=(value)
     if value < 1 || value > PBExperience.maxLevel
@@ -179,7 +206,7 @@ class PokeBattle_Pokemon
     return pbGetSpeciesData(@species,formSimple,SpeciesBaseExp)
   end
 
-  # @return [Float] number between 0 and 1 indicating how much of the current level's
+  # @return [Float] a number between 0 and 1 indicating how much of the current level's
   #   Exp this Pokémon has
   def expFraction
     l = self.level
@@ -303,18 +330,19 @@ class PokeBattle_Pokemon
     return abil!=nil && abil>=2
   end
 
-  # @return [Array<Array<Integer>>] the list of abilities this Pokémon can have
+  # @return [Array<Array<Integer>>] the list of abilities this Pokémon can have,
+  #   where every element is [ability ID,ability index]
   def getAbilityList
     ret = []
     abilities = pbGetSpeciesData(@species,formSimple,SpeciesAbilities)
     if abilities.is_a?(Array)
-      abilities.each_with_index { |a,i| ret.push([a,i]) if a && a>0 }
+      abilities.each_with_index { |a,i| ret.push([a,i]) if a && a > 0 }
     else
       ret.push([abilities,0]) if abilities>0
     end
     hiddenAbil = pbGetSpeciesData(@species,formSimple,SpeciesHiddenAbility)
     if hiddenAbil.is_a?(Array)
-      hiddenAbil.each_with_index { |a,i| ret.push([a,i+2]) if a && a>0 }
+      hiddenAbil.each_with_index { |a,i| ret.push([a,i+2]) if a && a > 0 }
     else
       ret.push([hiddenAbil,2]) if hiddenAbil>0
     end
@@ -327,12 +355,12 @@ class PokeBattle_Pokemon
 
   # @return [Integer] the ID of this Pokémon's nature
   def nature
-    return @natureflag || (@personalID%25)
+    return @natureflag || (@personalID % 25)
   end
 
   # Returns the calculated nature, taking into account things that change its
   # stat-altering effect (i.e. Gen 8 mints). Only used for calculating stats.
-  # @return [Integer] calculated nature
+  # @return [Integer] this Pokémon's calculated nature
   def calcNature
     return @natureOverride if @natureOverride
     return self.nature
@@ -350,7 +378,7 @@ class PokeBattle_Pokemon
   end
 
   # Sets this Pokémon's nature to a particular nature.
-  # @param value [Integer] nature to change to
+  # @param value [Integer, String, Symbol] nature to change to
   def setNature(value)
     @natureflag = getID(PBNatures,value)
     calcStats
@@ -387,14 +415,14 @@ class PokeBattle_Pokemon
 
   # @return [Integer] the Pokérus infection stage for this Pokémon
   def pokerusStrain
-    return @pokerus/16
+    return @pokerus / 16
   end
 
-  # Returns the Pokérus infection stage for this Pokémon.
-  # @return [0, 1, 2] Pokérus infection stage
-  #   (0 = not infected, 1 = infected, 2 = cured)
+  # Returns the Pokérus infection stage for this Pokémon. The possible stages are
+  # 0 (not infected), 1 (infected) and 2 (cured)
+  # @return [0, 1, 2] current Pokérus infection stage
   def pokerusStage
-    return 0 if !@pokerus || @pokerus==0
+    return 0 if !@pokerus || @pokerus == 0
     return 2 if @pokerus > 0 && (@pokerus % 16) == 0
     return 1
   end
@@ -470,7 +498,7 @@ class PokeBattle_Pokemon
     return ret
   end
 
-  # @param move [Integer, Symbol, String] id of the move to check
+  # @param move [Integer, Symbol, String] ID of the move to check
   # @return [Boolean] whether the Pokémon knows the given move
   def hasMove?(move)
     move = getID(PBMoves,move)
@@ -481,7 +509,7 @@ class PokeBattle_Pokemon
   alias knowsMove? hasMove?
 
   # Returns the list of moves this Pokémon can learn by levelling up.
-  # @return [Array<Array<Integer>>] move list, where every element is [level, move id]
+  # @return [Array<Array<Integer>>] this Pokémon's move list, where every element is [level, move ID]
   def getMoveList
     return pbGetSpeciesMoveset(@species,formSimple)
   end
@@ -506,7 +534,7 @@ class PokeBattle_Pokemon
   end
 
   # Silently learns the given move. Will erase the first known move if it has to.
-  # @param move [Integer, Symbol, String] id of the move to learn
+  # @param move [Integer, Symbol, String] ID of the move to learn
   def pbLearnMove(move)
     move = getID(PBMoves,move)
     return if move <= 0
@@ -535,7 +563,7 @@ class PokeBattle_Pokemon
   end
 
   # Deletes the given move from the Pokémon.
-  # @param move [Integer, Symbol, String] id of the move to delete
+  # @param move [Integer, Symbol, String] ID of the move to delete
   def pbDeleteMove(move)
     move = getID(PBMoves,move)
     return if !move || move<=0
@@ -571,14 +599,15 @@ class PokeBattle_Pokemon
     @moves.each { |m| @firstmoves.push(m.id) if m && m.id > 0 }
   end
 
-  # TODO Figure out better documentation for these first move methods
-  # @param move [Integer, Symbol, String] id of the move to add
+  # Adds a move to this Pokémon's first moves.
+  # @param move [Integer, Symbol, String] ID of the move to add
   def pbAddFirstMove(move)
     move = getID(PBMoves,move)
     @firstmoves.push(move) if move > 0 && !@firstmoves.include?(move)
   end
 
-  # @param move [Integer, Symbol, String] id of the move to remove
+  # Removes a move from this Pokémon's first moves.
+  # @param move [Integer, Symbol, String] ID of the move to remove
   def pbRemoveFirstMove(move)
     move = getID(PBMoves,move)
     @firstmoves.delete(move) if move > 0
@@ -589,8 +618,8 @@ class PokeBattle_Pokemon
     @firstmoves = []
   end
 
-  # @param move [Integer, Symbol, String] id of the move to check
-  # @return [Boolean] whether the Pokémon is compatible with the move
+  # @param move [Integer, Symbol, String] ID of the move to check
+  # @return [Boolean] whether the Pokémon is compatible with the given move
   def compatibleWithMove?(move)
     return pbSpeciesCompatible?(self.fSpecies,move)
   end
@@ -622,7 +651,7 @@ class PokeBattle_Pokemon
     return (@ribbons) ? @ribbons.length : 0
   end
 
-  # @param ribbon [Integer, Symbol, String] ribbon id to check
+  # @param ribbon [Integer, Symbol, String] ribbon ID to check
   # @return [Boolean] whether this Pokémon has the specified ribbon
   def hasRibbon?(ribbon)
     return false if !@ribbons
@@ -631,7 +660,8 @@ class PokeBattle_Pokemon
     return @ribbons.include?(ribbon)
   end
 
-  # @param ribbon [Integer, Symbol, String] id of the ribbon to give
+  # Gives a ribbon to this Pokémon.
+  # @param ribbon [Integer, Symbol, String] ID of the ribbon to give
   def giveRibbon(ribbon)
     @ribbons = [] if !@ribbons
     ribbon = getID(PBRibbons,ribbon)
@@ -639,7 +669,6 @@ class PokeBattle_Pokemon
     @ribbons.push(ribbon) if !@ribbons.include?(ribbon)
   end
 
-  # TODO Figure out a good way to document this
   # Replaces one ribbon with the next one along, if possible.
   def upgradeRibbon(*arg)
     @ribbons = [] if !@ribbons
@@ -661,6 +690,7 @@ class PokeBattle_Pokemon
     return 0
   end
 
+  # Removes the specified ribbon from this Pokémon.
   # @param ribbon [Integer, Symbol, String] id of the ribbon to remove
   def takeRibbon(ribbon)
     return if !@ribbons
@@ -750,13 +780,13 @@ class PokeBattle_Pokemon
   # Is 0, except if the Pokémon is:
   #
   # - Asleep: Is the number of rounds the Pokémon will remain asleep.
-  # This number is set when the Pokémon is made to fall asleep.
+  #   This number is set when the Pokémon is made to fall asleep.
   #
   # - Badly poisoned: If the Pokémon is Poisoned and this is "1", the
-  # Pokémon is badly poisoned instead (which affects how much poison
-  # damage it takes in battle). When the Pokémon leaves battle while
-  # badly poisoned, this value is set to 0 and it becomes regular Poisoned
-  # (even in later battles).
+  #   Pokémon is badly poisoned instead (which affects how much poison
+  #   damage it takes in battle). When the Pokémon leaves battle while
+  #   badly poisoned, this value is set to 0 and it becomes regular Poisoned
+  #   (even in later battles).
   # @return [Integer] sleep count / toxic flag
   def statusCount
     return @statusCount
@@ -857,13 +887,12 @@ class PokeBattle_Pokemon
     return "ABCDEFGHIJKLMNOPQRSTUVWXYZ?!"[@form,1]
   end
 
-  # TODO Check whether #height and #weight always return an integer
-  # Returns the height of this Pokémon.
+  # @return [Integer] the height of this Pokémon in decimetres (0.1 metres)
   def height
     return pbGetSpeciesData(@species,formSimple,SpeciesHeight)
   end
 
-  # Returns the weight of this Pokémon.
+  # @return [Integer] the weight of this Pokémon in hectograms (0.1 grams)
   def weight
     return pbGetSpeciesData(@species,formSimple,SpeciesWeight)
   end

From 37c1c208aa53b34644f1eae7875caec948c4e7e5 Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Fri, 18 Sep 2020 21:02:20 +0300
Subject: [PATCH 09/11] Added descriptions to #clone, #mail= and #setItem Also,
 improved the documentation of #name and #species

---
 Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 77e84551b..41b64cb5c 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -1,9 +1,9 @@
 # This class stores data on each Pokémon. Refer to $Trainer.party for an array
 # of each Pokémon in the Trainer's current party.
 class PokeBattle_Pokemon
-  # @return [String] the nickname
+  # @return [String] the nickname of this Pokémon
   attr_accessor :name
-  # @return [Integer] the national Pokédex number
+  # @return [Integer] this Pokémon's national Pokédex number
   attr_reader   :species
   # @return [Integer] the current experience points
   attr_reader   :exp
@@ -724,9 +724,10 @@ class PokeBattle_Pokemon
     return held_item == getID(PBItems,item_id)
   end
 
-  # @param item_id [Integer, Symbol, String] id of the item to give to this Pokémon
+  # Gives an item to this Pokémon. Passing 0 as the argument removes the held item.
+  # @param item_id [Integer, Symbol, String] id of the item to give to this Pokémon (0 removes held item)
   def setItem(item_id)
-    self.item = getID(PBItems,item_id)
+    self.item = item_id.is_a?(Integer) ? item_id : getID(PBItems,item_id)
   end
 
   # @return [Array<Integer>] the items this species can be found holding in the wild
@@ -745,6 +746,8 @@ class PokeBattle_Pokemon
     return @mail
   end
 
+  # If mail is a PokemonMail object, gives that mail to this Pokémon. If nil is given,
+  # removes the held mail.
   # @param mail [PokemonMail, nil] mail to be held by this Pokémon (nil if mail is to be removed)
   def mail=(mail)
     if !mail.nil? && !mail.is_a?(PokemonMail)
@@ -1038,6 +1041,7 @@ class PokeBattle_Pokemon
     @speed   = stats[PBStats::SPEED]
   end
 
+  # Creates a copy of this Pokémon and returns it.
   # @return [PokeBattle_Pokemon] a copy of this Pokémon
   def clone
     ret = super

From 3728afa6344939682367bca82de8737f58fb3ea6 Mon Sep 17 00:00:00 2001
From: jonisavo <joni@jonisavo.xyz>
Date: Sun, 20 Sep 2020 15:06:34 +0300
Subject: [PATCH 10/11] Improve PokeBattle_Pokemon#eggsteps's description

---
 Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 41b64cb5c..9bc6acd49 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -60,7 +60,7 @@ class PokeBattle_Pokemon
   attr_accessor :happiness
   # @return [Integer] the type of ball used (refer to {$BallTypes} for valid types)
   attr_accessor :ballused
-  # @return [Integer] the number of steps until the egg hatches, 0 if Pokémon is not an egg
+  # @return [Integer] the number of steps until this Pokémon hatches, 0 if this Pokémon is not an egg
   attr_accessor :eggsteps
   # @param value [Integer] new markings for this Pokémon
   attr_writer   :markings

From 1fe0d3645488397d66fda15970a81b0170c0ac0a Mon Sep 17 00:00:00 2001
From: Maruno17 <serialcolour@hotmail.com>
Date: Sun, 20 Sep 2020 17:00:41 +0100
Subject: [PATCH 11/11] Tidying

---
 .../016_Pokemon/001_PokeBattle_Pokemon.rb     | 340 +++++++++---------
 1 file changed, 171 insertions(+), 169 deletions(-)

diff --git a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
index 9bc6acd49..283cebbbd 100644
--- a/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
+++ b/Data/Scripts/016_Pokemon/001_PokeBattle_Pokemon.rb
@@ -1,5 +1,7 @@
-# This class stores data on each Pokémon. Refer to $Trainer.party for an array
-# of each Pokémon in the Trainer's current party.
+#===============================================================================
+# Instances of this class are individual Pokémon.
+# The player's party Pokémon are stored in the array $Trainer.party.
+#===============================================================================
 class PokeBattle_Pokemon
   # @return [String] the nickname of this Pokémon
   attr_accessor :name
@@ -15,18 +17,18 @@ class PokeBattle_Pokemon
   attr_reader   :attack
   # @return [Integer] the current Defense stat
   attr_reader   :defense
-  # @return [Integer] the current Speed stat
-  attr_reader   :speed
   # @return [Integer] the current Special Attack stat
   attr_reader   :spatk
   # @return [Integer] the current Special Defense stat
   attr_reader   :spdef
+  # @return [Integer] the current Speed stat
+  attr_reader   :speed
   # If defined, forces the Pokémon's ability to be the first natural (0),
-  # second natural (1) or hidden (2) ability available to its species.
+  # second natural (1) or a hidden (2-5) ability available to its species.
   # It is not possible to give the Pokémon any ability other than those
   # defined in the PBS file "pokemon.txt" for its species
   # (or "pokemonforms.txt" for its species and form). 
-  # @return [0, 1, 2, nil] forced ability index (nil if none is set)
+  # @return [0, 1, 2, 3, 4, 5, nil] forced ability index (nil if none is set)
   attr_accessor :abilityflag
   # If defined, forces this Pokémon to be male (0) or female (1).
   # @return [0, 1, nil] gender to force: male (0) or female (1) (nil if undefined)
@@ -46,6 +48,11 @@ class PokeBattle_Pokemon
   attr_accessor :firstmoves
   # @return [Integer] the ID of the item held by this Pokémon (0 = no held item)
   attr_accessor :item
+  # @return [Integer] this Pokémon's current status (from PBStatuses)
+  attr_reader   :status
+  # @return [Integer] sleep count / toxic flag / 0:
+  #   sleep (number of rounds before waking up), toxic (0 = regular poison, 1 = toxic)
+  attr_reader   :statusCount
   # Another Pokémon which has been fused with this Pokémon (or nil if there is none).
   # Currently only used by Kyurem, to record a fused Reshiram or Zekrom.  
   # @return [PokeBattle_Pokemon, nil] the Pokémon fused into this one (nil if there is none)
@@ -149,7 +156,7 @@ class PokeBattle_Pokemon
 
   # @return [Time] the time when this Pokémon hatched
   def timeEggHatched
-    if obtainMode==1
+    if obtainMode == 1
       return @timeEggHatched ? Time.at(@timeEggHatched) : Time.gm(2000)
     else
       return Time.gm(2000)
@@ -168,7 +175,7 @@ class PokeBattle_Pokemon
 
   # @return [Integer] this Pokémon's level
   def level
-    @level = PBExperience.pbGetLevelFromExperience(@exp,self.growthrate) if !@level
+    @level = PBExperience.pbGetLevelFromExperience(@exp, self.growthrate) if !@level
     return @level
   end
 
@@ -177,10 +184,10 @@ class PokeBattle_Pokemon
   # @param value [Integer] new level (between 1 and the maximum level)
   def level=(value)
     if value < 1 || value > PBExperience.maxLevel
-      raise ArgumentError.new(_INTL("The level number ({1}) is invalid.",value))
+      raise ArgumentError.new(_INTL("The level number ({1}) is invalid.", value))
     end
     @level = value
-    self.exp = PBExperience.pbGetStartExperience(value,self.growthrate)
+    self.exp = PBExperience.pbGetStartExperience(value, self.growthrate)
   end
 
   # Sets this Pokémon's Exp. Points.
@@ -198,23 +205,23 @@ class PokeBattle_Pokemon
 
   # @return [Integer] this Pokémon's growth rate (from PBGrowthRates)
   def growthrate
-    return pbGetSpeciesData(@species,formSimple,SpeciesGrowthRate)
+    return pbGetSpeciesData(@species, formSimple, SpeciesGrowthRate)
   end
 
   # @return [Integer] this Pokémon's base Experience value
   def baseExp
-    return pbGetSpeciesData(@species,formSimple,SpeciesBaseExp)
+    return pbGetSpeciesData(@species, formSimple, SpeciesBaseExp)
   end
 
   # @return [Float] a number between 0 and 1 indicating how much of the current level's
   #   Exp this Pokémon has
   def expFraction
-    l = self.level
-    return 0.0 if l >= PBExperience.maxLevel
-    gr = self.growthrate
-    startexp = PBExperience.pbGetStartExperience(l, gr)
-    endexp   = PBExperience.pbGetStartExperience(l + 1, gr)
-    return 1.0 * (@exp - startexp) / (endexp - startexp)
+    lvl = self.level
+    return 0.0 if lvl >= PBExperience.maxLevel
+    growth_rate = self.growthrate
+    start_exp = PBExperience.pbGetStartExperience(lvl, growth_rate)
+    end_exp   = PBExperience.pbGetStartExperience(lvl + 1, growth_rate)
+    return 1.0 * (@exp - start_exp) / (end_exp - start_exp)
   end
 
   #=============================================================================
@@ -224,24 +231,24 @@ class PokeBattle_Pokemon
   # @return [0, 1, 2] this Pokémon's gender (0 = male, 1 = female, 2 = genderless)
   def gender
     # Return sole gender option for all male/all female/genderless species
-    genderRate = pbGetSpeciesData(@species,formSimple,SpeciesGenderRate)
-    case genderRate
+    gender_rate = pbGetSpeciesData(@species, formSimple, SpeciesGenderRate)
+    case gender_rate
     when PBGenderRates::AlwaysMale;   return 0
     when PBGenderRates::AlwaysFemale; return 1
     when PBGenderRates::Genderless;   return 2
     end
     # Return gender for species that can be male or female
     return @genderflag if @genderflag && (@genderflag == 0 || @genderflag == 1)
-    return ((@personalID & 0xFF) < PBGenderRates.genderByte(genderRate)) ? 1 : 0
+    return ((@personalID & 0xFF) < PBGenderRates.genderByte(gender_rate)) ? 1 : 0
   end
 
   # @return [Boolean] whether this Pokémon species is restricted to only ever being one
   #   gender (or genderless)
   def singleGendered?
-    genderRate = pbGetSpeciesData(@species,formSimple,SpeciesGenderRate)
-    return genderRate == PBGenderRates::AlwaysMale ||
-           genderRate == PBGenderRates::AlwaysFemale ||
-           genderRate == PBGenderRates::Genderless
+    gender_rate = pbGetSpeciesData(@species, formSimple, SpeciesGenderRate)
+    return gender_rate == PBGenderRates::AlwaysMale ||
+           gender_rate == PBGenderRates::AlwaysFemale ||
+           gender_rate == PBGenderRates::Genderless
   end
   alias isSingleGendered? singleGendered?
 
@@ -270,7 +277,7 @@ class PokeBattle_Pokemon
   end
 
   # Makes this Pokémon male.
-  def makeMale;   setGender(0); end
+  def makeMale; setGender(0); end
   # Makes this Pokémon female.
   def makeFemale; setGender(1); end
 
@@ -288,7 +295,7 @@ class PokeBattle_Pokemon
     abilIndex = abilityIndex
     # Hidden ability
     if abilIndex >= 2
-      hiddenAbil = pbGetSpeciesData(@species,formSimple,SpeciesHiddenAbility)
+      hiddenAbil = pbGetSpeciesData(@species, formSimple, SpeciesHiddenAbility)
       if hiddenAbil.is_a?(Array)
         ret = hiddenAbil[abilIndex - 2]
         return ret if ret && ret > 0
@@ -298,7 +305,7 @@ class PokeBattle_Pokemon
       abilIndex = (@personalID & 1)
     end
     # Natural ability
-    abilities = pbGetSpeciesData(@species,formSimple,SpeciesAbilities)
+    abilities = pbGetSpeciesData(@species, formSimple, SpeciesAbilities)
     if abilities.is_a?(Array)
       ret = abilities[abilIndex]
       ret = abilities[(abilIndex + 1) % 2] if !ret || ret == 0
@@ -315,7 +322,7 @@ class PokeBattle_Pokemon
   def hasAbility?(ability = 0)
     current_ability = self.ability
     return current_ability > 0 if ability == 0
-    return current_ability == getID(PBAbilities,ability)
+    return current_ability == getID(PBAbilities, ability)
   end
 
   # Sets this Pokémon's ability index.
@@ -327,24 +334,24 @@ class PokeBattle_Pokemon
   # @return [Boolean] whether this Pokémon has a hidden ability
   def hasHiddenAbility?
     abil = abilityIndex
-    return abil!=nil && abil>=2
+    return abil != nil && abil >= 2
   end
 
   # @return [Array<Array<Integer>>] the list of abilities this Pokémon can have,
-  #   where every element is [ability ID,ability index]
+  #   where every element is [ability ID, ability index]
   def getAbilityList
     ret = []
-    abilities = pbGetSpeciesData(@species,formSimple,SpeciesAbilities)
+    abilities = pbGetSpeciesData(@species, formSimple, SpeciesAbilities)
     if abilities.is_a?(Array)
-      abilities.each_with_index { |a,i| ret.push([a,i]) if a && a > 0 }
+      abilities.each_with_index { |a, i| ret.push([a, i]) if a && a > 0 }
     else
-      ret.push([abilities,0]) if abilities>0
+      ret.push([abilities, 0]) if abilities > 0
     end
-    hiddenAbil = pbGetSpeciesData(@species,formSimple,SpeciesHiddenAbility)
+    hiddenAbil = pbGetSpeciesData(@species, formSimple, SpeciesHiddenAbility)
     if hiddenAbil.is_a?(Array)
-      hiddenAbil.each_with_index { |a,i| ret.push([a,i+2]) if a && a > 0 }
+      hiddenAbil.each_with_index { |a, i| ret.push([a, i + 2]) if a && a > 0 }
     else
-      ret.push([hiddenAbil,2]) if hiddenAbil>0
+      ret.push([hiddenAbil, 2]) if hiddenAbil > 0
     end
     return ret
   end
@@ -374,13 +381,13 @@ class PokeBattle_Pokemon
   def hasNature?(nature = -1)
     current_nature = self.nature
     return current_nature >= 0 if nature < 0
-    return current_nature == getID(PBNatures,nature)
+    return current_nature == getID(PBNatures, nature)
   end
 
   # Sets this Pokémon's nature to a particular nature.
   # @param value [Integer, String, Symbol] nature to change to
   def setNature(value)
-    @natureflag = getID(PBNatures,value)
+    @natureflag = getID(PBNatures, value)
     calcStats
   end
 
@@ -458,22 +465,22 @@ class PokeBattle_Pokemon
 
   # @return [Integer] this Pokémon's first type
   def type1
-    return pbGetSpeciesData(@species,formSimple,SpeciesType1)
+    return pbGetSpeciesData(@species, formSimple, SpeciesType1)
   end
 
   # @return [Integer] this Pokémon's second type, or the first type if none is defined
   def type2
-    ret = pbGetSpeciesData(@species,formSimple,SpeciesType2)
-    ret = pbGetSpeciesData(@species,formSimple,SpeciesType1) if !ret
+    ret = pbGetSpeciesData(@species, formSimple, SpeciesType2)
+    ret = pbGetSpeciesData(@species, formSimple, SpeciesType1) if !ret
     return ret
   end
 
   # @return [Array<Integer>] an array of this Pokémon's types
   def types
-    ret1 = pbGetSpeciesData(@species,formSimple,SpeciesType1)
-    ret2 = pbGetSpeciesData(@species,formSimple,SpeciesType2)
+    ret1 = pbGetSpeciesData(@species, formSimple, SpeciesType1)
+    ret2 = pbGetSpeciesData(@species, formSimple, SpeciesType2)
     ret = [ret1]
-    ret.push(ret2) if ret2 && ret2!=ret1
+    ret.push(ret2) if ret2 && ret2 != ret1
     return ret
   end
 
@@ -482,7 +489,7 @@ class PokeBattle_Pokemon
   def hasType?(type)
     t = self.types
     if !type.is_a?(Integer)
-      return t.any? { |tp| isConst?(tp,PBTypes,type) }
+      return t.any? { |tp| isConst?(tp, PBTypes, type) }
     end
     return t.any? { |tp| tp == type }
   end
@@ -501,7 +508,7 @@ class PokeBattle_Pokemon
   # @param move [Integer, Symbol, String] ID of the move to check
   # @return [Boolean] whether the Pokémon knows the given move
   def hasMove?(move)
-    move = getID(PBMoves,move)
+    move = getID(PBMoves, move)
     return false if !move || move <= 0
     @moves.each { |m| return true if m && m.id == move }
     return false
@@ -511,7 +518,7 @@ class PokeBattle_Pokemon
   # Returns the list of moves this Pokémon can learn by levelling up.
   # @return [Array<Array<Integer>>] this Pokémon's move list, where every element is [level, move ID]
   def getMoveList
-    return pbGetSpeciesMoveset(@species,formSimple)
+    return pbGetSpeciesMoveset(@species, formSimple)
   end
 
   # Sets this Pokémon's movelist to the default movelist it originally had.
@@ -536,7 +543,7 @@ class PokeBattle_Pokemon
   # Silently learns the given move. Will erase the first known move if it has to.
   # @param move [Integer, Symbol, String] ID of the move to learn
   def pbLearnMove(move)
-    move = getID(PBMoves,move)
+    move = getID(PBMoves, move)
     return if move <= 0
     for i in 0...4   # Already knows move, relocate it to the end of the list
       next if @moves[i].id != move
@@ -566,7 +573,7 @@ class PokeBattle_Pokemon
   # @param move [Integer, Symbol, String] ID of the move to delete
   def pbDeleteMove(move)
     move = getID(PBMoves,move)
-    return if !move || move<=0
+    return if !move || move <= 0
     newMoves = []
     @moves.each { |m| newMoves.push(m) if m && m.id != move }
     newMoves.push(PBMove.new(0))
@@ -579,7 +586,7 @@ class PokeBattle_Pokemon
   # @param index [Integer] index of the move to be deleted
   def pbDeleteMoveAtIndex(index)
     newMoves = []
-    @moves.each_with_index { |m,i| newMoves.push(m) if m && i != index }
+    @moves.each_with_index { |m, i| newMoves.push(m) if m && i != index }
     newMoves.push(PBMove.new(0))
     for i in 0...4
       @moves[i] = newMoves[i]
@@ -602,14 +609,14 @@ class PokeBattle_Pokemon
   # Adds a move to this Pokémon's first moves.
   # @param move [Integer, Symbol, String] ID of the move to add
   def pbAddFirstMove(move)
-    move = getID(PBMoves,move)
+    move = getID(PBMoves, move)
     @firstmoves.push(move) if move > 0 && !@firstmoves.include?(move)
   end
 
   # Removes a move from this Pokémon's first moves.
   # @param move [Integer, Symbol, String] ID of the move to remove
   def pbRemoveFirstMove(move)
-    move = getID(PBMoves,move)
+    move = getID(PBMoves, move)
     @firstmoves.delete(move) if move > 0
   end
 
@@ -621,7 +628,7 @@ class PokeBattle_Pokemon
   # @param move [Integer, Symbol, String] ID of the move to check
   # @return [Boolean] whether the Pokémon is compatible with the given move
   def compatibleWithMove?(move)
-    return pbSpeciesCompatible?(self.fSpecies,move)
+    return pbSpeciesCompatible?(self.fSpecies, move)
   end
 
   #=============================================================================
@@ -629,22 +636,34 @@ class PokeBattle_Pokemon
   #=============================================================================
 
   # @return [Integer] this Pokémon's cool contest attribute
-  def cool; return @cool || 0; end
+  def cool
+    return @cool || 0
+  end
 
   # @return [Integer] this Pokémon's beauty contest attribute
-  def beauty; return @beauty || 0; end
+  def beauty
+    return @beauty || 0
+  end
 
   # @return [Integer] this Pokémon's cute contest attribute
-  def cute; return @cute || 0; end
+  def cute
+    return @cute || 0
+  end
 
   # @return [Integer] this Pokémon's smart contest attribute
-  def smart; return @smart || 0; end
+  def smart
+    return @smart || 0
+  end
 
   # @return [Integer] this Pokémon's tough contest attribute
-  def tough; return @tough || 0; end
+  def tough;
+    return @tough || 0
+  end
 
   # @return [Integer] this Pokémon's sheen contest attribute
-  def sheen; return @sheen || 0; end
+  def sheen
+    return @sheen || 0
+  end
   
   # @return [Integer] the number of ribbons this Pokémon has
   def ribbonCount
@@ -655,7 +674,7 @@ class PokeBattle_Pokemon
   # @return [Boolean] whether this Pokémon has the specified ribbon
   def hasRibbon?(ribbon)
     return false if !@ribbons
-    ribbon = getID(PBRibbons,ribbon)
+    ribbon = getID(PBRibbons, ribbon)
     return false if ribbon == 0
     return @ribbons.include?(ribbon)
   end
@@ -664,7 +683,7 @@ class PokeBattle_Pokemon
   # @param ribbon [Integer, Symbol, String] ID of the ribbon to give
   def giveRibbon(ribbon)
     @ribbons = [] if !@ribbons
-    ribbon = getID(PBRibbons,ribbon)
+    ribbon = getID(PBRibbons, ribbon)
     return if ribbon == 0
     @ribbons.push(ribbon) if !@ribbons.include?(ribbon)
   end
@@ -672,18 +691,18 @@ class PokeBattle_Pokemon
   # Replaces one ribbon with the next one along, if possible.
   def upgradeRibbon(*arg)
     @ribbons = [] if !@ribbons
-    for i in 0...arg.length-1
+    for i in 0...arg.length - 1
       for j in 0...@ribbons.length
-        thisribbon = (arg[i].is_a?(Integer)) ? arg[i] : getID(PBRibbons,arg[i])
-        if @ribbons[j]==thisribbon
-          nextribbon = (arg[i+1].is_a?(Integer)) ? arg[i+1] : getID(PBRibbons,arg[i+1])
+        thisribbon = (arg[i].is_a?(Integer)) ? arg[i] : getID(PBRibbons, arg[i])
+        if @ribbons[j] == thisribbon
+          nextribbon = (arg[i+1].is_a?(Integer)) ? arg[i+1] : getID(PBRibbons, arg[i+1])
           @ribbons[j] = nextribbon
           return nextribbon
         end
       end
     end
-    if !hasRibbon?(arg[arg.length-1])
-      firstribbon = (arg[0].is_a?(Integer)) ? arg[0] : getID(PBRibbons,arg[0])
+    if !hasRibbon?(arg[arg.length - 1])
+      firstribbon = (arg[0].is_a?(Integer)) ? arg[0] : getID(PBRibbons, arg[0])
       giveRibbon(firstribbon)
       return firstribbon
     end
@@ -694,10 +713,10 @@ class PokeBattle_Pokemon
   # @param ribbon [Integer, Symbol, String] id of the ribbon to remove
   def takeRibbon(ribbon)
     return if !@ribbons
-    ribbon = getID(PBRibbons,ribbon)
-    return if ribbon==0
+    ribbon = getID(PBRibbons, ribbon)
+    return if ribbon == 0
     for i in 0...@ribbons.length
-      next if @ribbons[i]!=ribbon
+      next if @ribbons[i] != ribbon
       @ribbons[i] = nil
       break
     end
@@ -721,21 +740,21 @@ class PokeBattle_Pokemon
   def hasItem?(item_id = 0)
     held_item = self.item
     return held_item > 0 if item_id == 0
-    return held_item == getID(PBItems,item_id)
+    return held_item == getID(PBItems, item_id)
   end
 
   # Gives an item to this Pokémon. Passing 0 as the argument removes the held item.
   # @param item_id [Integer, Symbol, String] id of the item to give to this Pokémon (0 removes held item)
   def setItem(item_id)
-    self.item = item_id.is_a?(Integer) ? item_id : getID(PBItems,item_id)
+    self.item = getID(PBItems, item_id) || 0
   end
 
   # @return [Array<Integer>] the items this species can be found holding in the wild
   def wildHoldItems
     ret = []
-    ret.push(pbGetSpeciesData(@species,formSimple,SpeciesWildItemCommon))
-    ret.push(pbGetSpeciesData(@species,formSimple,SpeciesWildItemUncommon))
-    ret.push(pbGetSpeciesData(@species,formSimple,SpeciesWildItemRare))
+    ret.push(pbGetSpeciesData(@species, formSimple, SpeciesWildItemCommon))
+    ret.push(pbGetSpeciesData(@species, formSimple, SpeciesWildItemUncommon))
+    ret.push(pbGetSpeciesData(@species, formSimple, SpeciesWildItemRare))
     return ret
   end
 
@@ -751,7 +770,7 @@ class PokeBattle_Pokemon
   # @param mail [PokemonMail, nil] mail to be held by this Pokémon (nil if mail is to be removed)
   def mail=(mail)
     if !mail.nil? && !mail.is_a?(PokemonMail)
-      raise ArgumentError, _INTL('Invalid value {1} given',mail.inspect)
+      raise ArgumentError, _INTL('Invalid value {1} given', mail.inspect)
     end
     @mail = mail
   end
@@ -760,39 +779,14 @@ class PokeBattle_Pokemon
   # Status
   #=============================================================================
 
-  # Returns the current status of this Pokémon. See {PBStatuses} for all possible
-  # status effects.
-  # @return [Integer] current status (from PBStatuses)
-  def status
-    return @status
-  end
-
   # Sets this Pokémon's status. See {PBStatuses} for all possible status effects.
   # @param new_status [Integer, Symbol, String] status to set (from PBStatuses)
-  def status=(new_status)
-    if new_status.is_a?(Integer)
-      @status = new_status
-    else
-      if !new_status.is_a?(Symbol) && !new_status.is_a?(String)
-        raise ArgumentError, _INTL('Attempted to set a {1} as Pokémon status',new_status.class.name)
-      end
-      @status = getID(PBStatuses,new_status)
+  def status=(value)
+    new_status = getID(PBStatuses, value)
+    if !new_status
+      raise ArgumentError, _INTL('Attempted to set {1} as Pokémon status', value.class.name)
     end
-  end
-
-  # Is 0, except if the Pokémon is:
-  #
-  # - Asleep: Is the number of rounds the Pokémon will remain asleep.
-  #   This number is set when the Pokémon is made to fall asleep.
-  #
-  # - Badly poisoned: If the Pokémon is Poisoned and this is "1", the
-  #   Pokémon is badly poisoned instead (which affects how much poison
-  #   damage it takes in battle). When the Pokémon leaves battle while
-  #   badly poisoned, this value is set to 0 and it becomes regular Poisoned
-  #   (even in later battles).
-  # @return [Integer] sleep count / toxic flag
-  def statusCount
-    return @statusCount
+    @status = new_status
   end
 
   # Sets a new status count. See {#statusCount} for more information.
@@ -826,7 +820,7 @@ class PokeBattle_Pokemon
     @statusCount = 0
   end
   
-  # Heals all PP of this Pokémon. If a move index is given, heals the PP
+  # Restores all PP of this Pokémon. If a move index is given, restores the PP
   # of the move in that index.
   # @param move_index [Integer] index of the move to heal (-1 if all moves
   #   should be healed)
@@ -854,9 +848,9 @@ class PokeBattle_Pokemon
   # Changes the Pokémon's species and re-calculates its statistics.
   # @param species_id [Integer] id of the species to change this Pokémon to
   def species=(species_id)
-    hasNickname = nicknamed?
+    has_nickname = nicknamed?
     @species    = species_id
-    @name       = PBSpecies.getName(@species) unless hasNickname
+    @name       = PBSpecies.getName(@species) unless has_nickname
     @level      = nil   # In case growth rate is different for the new species
     @forcedForm = nil
     calcStats
@@ -865,7 +859,7 @@ class PokeBattle_Pokemon
   # @param species [Integer, Symbol, String] id of the species to check for
   # @return [Boolean] whether this Pokémon is of the specified species
   def isSpecies?(species)
-    species = getID(PBSpecies,species)
+    species = getID(PBSpecies, species)
     return species && @species == species
   end
 
@@ -880,29 +874,33 @@ class PokeBattle_Pokemon
   end
 
   # @return [Integer] this Pokémon's language
-  def language; return @language || 0; end
+  def language
+    return @language || 0
+  end
 
   # @return [Integer] the markings this Pokémon has
-  def markings; return @markings || 0; end
+  def markings
+    return @markings || 0
+  end
 
   # @return [String] a string stating the Unown form of this Pokémon
   def unownShape
-    return "ABCDEFGHIJKLMNOPQRSTUVWXYZ?!"[@form,1]
+    return "ABCDEFGHIJKLMNOPQRSTUVWXYZ?!"[@form, 1]
   end
 
   # @return [Integer] the height of this Pokémon in decimetres (0.1 metres)
   def height
-    return pbGetSpeciesData(@species,formSimple,SpeciesHeight)
+    return pbGetSpeciesData(@species, formSimple, SpeciesHeight)
   end
 
-  # @return [Integer] the weight of this Pokémon in hectograms (0.1 grams)
+  # @return [Integer] the weight of this Pokémon in hectograms (0.1 kilograms)
   def weight
-    return pbGetSpeciesData(@species,formSimple,SpeciesWeight)
+    return pbGetSpeciesData(@species, formSimple, SpeciesWeight)
   end
 
   # Returns an array of booleans indicating whether a stat is made to have
   # maximum IVs (for Hyper Training). Set like @ivMaxed[PBStats::ATTACK] = true
-  # @return [Array<Boolean>] array indicating whether a stat has maximum IVs
+  # @return [Array<Boolean>] array indicating whether each stat has maximum IVs
   def ivMaxed
     return @ivMaxed || []
   end
@@ -920,7 +918,7 @@ class PokeBattle_Pokemon
 
   # @return [Array<Integer>] the EV yield of this Pokémon (an array of six values)
   def evYield
-    ret = pbGetSpeciesData(@species,formSimple,SpeciesEffortPoints)
+    ret = pbGetSpeciesData(@species, formSimple, SpeciesEffortPoints)
     return ret.clone
   end
 
@@ -942,77 +940,77 @@ class PokeBattle_Pokemon
     case method
     when "walking"
       gain = 1
-      gain = 2 if @happiness<200
+      gain = 2 if @happiness < 200
     when "levelup"
       gain = 3
-      gain = 4 if @happiness<200
-      gain = 5 if @happiness<100
+      gain = 4 if @happiness < 200
+      gain = 5 if @happiness < 100
     when "groom"
       gain = 4
-      gain = 10 if @happiness<200
+      gain = 10 if @happiness < 200
     when "evberry"
       gain = 2
-      gain = 5 if @happiness<200
-      gain = 10 if @happiness<100
+      gain = 5 if @happiness < 200
+      gain = 10 if @happiness < 100
     when "vitamin"
       gain = 2
-      gain = 3 if @happiness<200
-      gain = 5 if @happiness<100
+      gain = 3 if @happiness < 200
+      gain = 5 if @happiness < 100
     when "wing"
       gain = 1
-      gain = 2 if @happiness<200
-      gain = 3 if @happiness<100
+      gain = 2 if @happiness < 200
+      gain = 3 if @happiness < 100
     when "machine"
       gain = 0
-      gain = 1 if @happiness<200
+      gain = 1 if @happiness < 200
     when "battleitem"
       gain = 0
-      gain = 1 if @happiness<200
+      gain = 1 if @happiness < 200
     when "faint"
       gain = -1
     when "faintbad"   # Fainted against an opponent that is 30+ levels higher
       gain = -10
-      gain = -5 if @happiness<200
+      gain = -5 if @happiness < 200
     when "powder"
       gain = -10
-      gain = -5 if @happiness<200
+      gain = -5 if @happiness < 200
     when "energyroot"
       gain = -15
-      gain = -10 if @happiness<200
+      gain = -10 if @happiness < 200
     when "revivalherb"
       gain = -20
-      gain = -15 if @happiness<200
+      gain = -15 if @happiness < 200
     else
-      raise _INTL("Unknown happiness-changing method: {1}",method.to_s)
+      raise _INTL("Unknown happiness-changing method: {1}", method.to_s)
     end
-    if gain>0
-      gain += 1 if @obtainMap==$game_map.map_id
-      gain += 1 if self.ballused==pbGetBallType(:LUXURYBALL)
-      gain = (gain*1.5).floor if self.hasItem?(:SOOTHEBELL)
+    if gain > 0
+      gain += 1 if @obtainMap == $game_map.map_id
+      gain += 1 if self.ballused == pbGetBallType(:LUXURYBALL)
+      gain = (gain * 1.5).floor if self.hasItem?(:SOOTHEBELL)
     end
     @happiness += gain
-    @happiness = [[255,@happiness].min,0].max
+    @happiness = [[255, @happiness].min, 0].max
   end
 
   #=============================================================================
-  # Stat calculations, Pokémon creation
+  # Stat calculations
   #=============================================================================
 
   # @return [Array<Integer>] this Pokémon's base stats, an array of six values
   def baseStats
-    ret = pbGetSpeciesData(@species,formSimple,SpeciesBaseStats)
+    ret = pbGetSpeciesData(@species, formSimple, SpeciesBaseStats)
     return ret.clone
   end
 
   # @return [Integer] the maximum HP of this Pokémon
-  def calcHP(base,level,iv,ev)
+  def calcHP(base, level, iv, ev)
     return 1 if base == 1   # For Shedinja
-    return ((base * 2 + iv + (ev >> 2)) * level / 100).floor + level + 10
+    return ((base * 2 + iv + (ev / 4)) * level / 100).floor + level + 10
   end
 
   # @return [Integer] the specified stat of this Pokémon (not used for total HP)
-  def calcStat(base,level,iv,ev,pv)
-    return ((((base*2+iv+(ev>>2))*level/100).floor+5)*pv/100).floor
+  def calcStat(base, level, iv, ev, pv)
+    return ((((base * 2 + iv + (ev / 4)) * level / 100).floor + 5) * pv / 100).floor
   end
 
   # Recalculates this Pokémon's stats.
@@ -1023,17 +1021,17 @@ class PokeBattle_Pokemon
     pValues   = PBNatures.getStatChanges(self.calcNature)
     stats = []
     PBStats.eachStat do |s|
-      if s==PBStats::HP
-        stats[s] = calcHP(bs[s],usedLevel,usedIV[s],@ev[s])
+      if s == PBStats::HP
+        stats[s] = calcHP(bs[s], usedLevel, usedIV[s], @ev[s])
       else
-        stats[s] = calcStat(bs[s],usedLevel,usedIV[s],@ev[s],pValues[s])
+        stats[s] = calcStat(bs[s], usedLevel, usedIV[s], @ev[s], pValues[s])
       end
     end
-    hpDiff = @totalhp-@hp
+    hpDiff = @totalhp - @hp
     @totalhp = stats[PBStats::HP]
-    @hp      = @totalhp-hpDiff
-    @hp      = 0 if @hp<0
-    @hp      = @totalhp if @hp>@totalhp
+    @hp      = @totalhp - hpDiff
+    @hp      = 0 if @hp < 0
+    @hp      = @totalhp if @hp > @totalhp
     @attack  = stats[PBStats::ATTACK]
     @defense = stats[PBStats::DEFENSE]
     @spatk   = stats[PBStats::SPATK]
@@ -1041,6 +1039,10 @@ class PokeBattle_Pokemon
     @speed   = stats[PBStats::SPEED]
   end
 
+  #=============================================================================
+  # Pokémon creation
+  #=============================================================================
+
   # Creates a copy of this Pokémon and returns it.
   # @return [PokeBattle_Pokemon] a copy of this Pokémon
   def clone
@@ -1049,7 +1051,7 @@ class PokeBattle_Pokemon
     ret.ivMaxed = @ivMaxed.clone
     ret.ev      = @ev.clone
     ret.moves   = []
-    @moves.each_with_index { |m,i| ret.moves[i] = m.clone }
+    @moves.each_with_index { |m, i| ret.moves[i] = m.clone }
     ret.ribbons = @ribbons.clone if @ribbons
     return ret
   end
@@ -1059,27 +1061,24 @@ class PokeBattle_Pokemon
   # @param level [Integer] Pokémon level
   # @param player [PokeBattle_Trainer] object for the original trainer
   # @param withMoves [Boolean] whether the Pokémon should have moves
-  def initialize(species,level,player=nil,withMoves=true)
+  def initialize(species, level, player = nil, withMoves = true)
     ospecies = species.to_s
-    species = getID(PBSpecies,species)
-    cname = getConstantName(PBSpecies,species) rescue nil
+    species = getID(PBSpecies, species)
+    cname = getConstantName(PBSpecies, species) rescue nil
     realSpecies = pbGetSpeciesFromFSpecies(species)[0] if species && species > 0
-    if !species || species<=0 || realSpecies > PBSpecies.maxValue || !cname
-      raise ArgumentError.new(_INTL("The species given ({1}) is invalid.",ospecies))
+    if !species || species <= 0 || realSpecies > PBSpecies.maxValue || !cname
+      raise ArgumentError.new(_INTL("The species given ({1}) is invalid.", ospecies))
     end
     @species      = realSpecies
     @name         = PBSpecies.getName(@species)
-    @personalID   = rand(256)
-    @personalID   |= rand(256)<<8
-    @personalID   |= rand(256)<<16
-    @personalID   |= rand(256)<<24
+    @personalID   = rand(2**32)
     @hp           = 1
     @totalhp      = 1
     @iv           = []
     @ivMaxed      = []
     @ev           = []
     PBStats.eachStat do |s|
-      @iv[s]      = rand(IV_STAT_LIMIT+1)
+      @iv[s]      = rand(IV_STAT_LIMIT + 1)
       @ev[s]      = 0
     end
     @moves        = []
@@ -1111,7 +1110,7 @@ class PokeBattle_Pokemon
     self.level    = level
     calcStats
     @hp           = @totalhp
-    @happiness    = pbGetSpeciesData(@species,formSimple,SpeciesHappiness)
+    @happiness    = pbGetSpeciesData(@species, formSimple, SpeciesHappiness)
     if withMoves
       self.resetMoves
     else
@@ -1122,14 +1121,17 @@ class PokeBattle_Pokemon
   end
 end
 
+#===============================================================================
+#
+#===============================================================================
+
 # Creates a new Pokémon object.
 # @param species [Integer, Symbol, String] Pokémon species
 # @param level [Integer] Pokémon level
 # @param owner [PokeBattle_Trainer] object for the original trainer
 # @param withMoves [Boolean] whether the Pokémon should have moves
-def pbNewPkmn(species,level,owner=nil,withMoves=true)
-  owner = $Trainer if !owner
-  return PokeBattle_Pokemon.new(species,level,owner,withMoves)
+def pbNewPkmn(species, level, owner = $Trainer, withMoves = true)
+  return PokeBattle_Pokemon.new(species, level, owner, withMoves)
 end
 alias pbGenPkmn pbNewPkmn
 alias pbGenPoke pbNewPkmn