More work on documentation

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,7 +460,8 @@ 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)
@@ -452,14 +473,16 @@ class PokeBattle_Pokemon
   #=============================================================================
   # 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 }
     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
@@ -469,6 +492,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]
   def getMoveList
     return pbGetSpeciesMoveset(@species,formSimple)
   end
@@ -493,6 +517,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
   def pbLearnMove(move)
     move = getID(PBMoves,move)
     return if move <= 0
@@ -521,6 +546,7 @@ 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
@@ -533,6 +559,7 @@ 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 }
@@ -555,11 +582,14 @@ 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
   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
   def pbRemoveFirstMove(move)
     move = getID(PBMoves,move)
     @firstmoves.delete(move) if move > 0
@@ -569,6 +599,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
   def compatibleWithMove?(move)
     return pbSpeciesCompatible?(self.fSpecies,move)
   end