Added Trainer documentation

2 files changed, 149 insertions, 1 deletions

diff --git a/sigmod/Trainer.cpp b/sigmod/Trainer.cpp
index 17a8d955..cd91a511 100644
--- a/sigmod/Trainer.cpp
+++ b/sigmod/Trainer.cpp
@@ -15,6 +15,10 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * \file sigmod/Trainer.cpp
+ */
+
 // Header include
 #include "Trainer.h"
 
diff --git a/sigmod/Trainer.h b/sigmod/Trainer.h
index 17c4d29a..152699ba 100644
--- a/sigmod/Trainer.h
+++ b/sigmod/Trainer.h
@@ -1,5 +1,5 @@
 /*
- * Copyright 2008 Ben Boeckel <MathStuf@gmail.com>
+ * Copyright 2008-2009 Ben Boeckel <MathStuf@gmail.com>
  * 
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -15,6 +15,10 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * \file sigmod/Trainer.h
+ */
+
 #ifndef SIGMOD_TRAINER
 #define SIGMOD_TRAINER
 
@@ -29,6 +33,16 @@ namespace Sigmod
 // Forward declarations
 class Sigmod;
 
+/**
+ * \class Sigmod::Trainer Trainer.h sigmod/Trainer.h
+ * \brief Class describing a trainer class.
+ * 
+ * A trainer class allows all trainers of a type to be defined once. They can have
+ * a depth which is the farthest ahead they can perceive the battle before making
+ * decisions about actions. The knowledge of different aspects of battle allow the
+ * AI controlling the trainer to gather information about the battle to make better
+ * decisions.
+ */
 class SIGMOD_EXPORT Trainer : public Object
 {
     Q_OBJECT
@@ -44,34 +58,164 @@ class SIGMOD_EXPORT Trainer : public Object
         };
         static const QStringList IntelligenceStr;
         
+        /**
+         * Copy constructor.
+         * 
+         * \param trainer The trainer to copy.
+         */
         Trainer(const Trainer& trainer);
+        /**
+         * Create a new trainer belonging to \p parent and id \p id.
+         * 
+         * \param parent The parent of the trainer.
+         * \param id The id number for the trainer.
+         */
         Trainer(const Sigmod* parent, const int id);
+        /**
+         * Data copy constructor. Copies the data from \p trainer as a child of \p parent with id \p id.
+         * 
+         * \param trainer The trainer to copy the data from.
+         * \param parent The parent of the trainer.
+         * \param id The id number for the trainer.
+         */
         Trainer(const Trainer& trainer, const Sigmod* parent, const int id);
+        /**
+         * XML data constructor.
+         * 
+         * \param xml The XML structure to extract the data from.
+         * \param parent The parent of the trainer.
+         * \param id The id number for the trainer.
+         */
         Trainer(const QDomElement& xml, const Sigmod* parent, const int id = -1);
         
+        /**
+         * Check to make sure the trainer's values are valid.
+         */
         void validate();
         
+        /**
+         * Load data from XML.
+         * 
+         * \param xml The XML structure to extract data from.
+         */
         void load(const QDomElement& xml);
+        /**
+         * Get the data for the trainer in XML format.
+         * 
+         * \return The XML structure representing the trainer.
+         */
         QDomElement save() const;
         
+        /**
+         * Sets the name of the trainer. This is only used internally.
+         * 
+         * \param name The name of the trainer class.
+         */
         void setName(const QString& name);
+        /**
+         * Sets the multiplier for money when defeated.
+         * 
+         * \param moneyFactor The multiplier for the money reward for defeating the trainer.
+         */
         void setMoneyFactor(const int moneyFactor);
+        /**
+         * Sets the skin that is used to represent the trainer on the world map.
+         * 
+         * \param skin The id of the skin used to represent the trainer.
+         */
         void setSkin(const int skin);
+        /**
+         * Sets the maximum depth that the AI can predict. If the battle arena uses turns,
+         * the AI counts as one depth as one round of turns; in an ATB arena, one depth is
+         * predicted moves until the same creature attacks again.
+         * 
+         * \param depth The maximum depth the AI can predict.
+         */
         void setDepth(const int depth);
+        /**
+         * Sets the level of knowledge the trainer has about enemy teams.
+         * 
+         * \param teamIntel The level of knowledge the trainer has about enemy teams.
+         */
         void setTeamIntel(const Intelligence teamIntel);
+        /**
+         * Sets the level of knowledge the trainer has about enemy moves.
+         * 
+         * \param moveIntel The level of knowledge the trainer has about enemy moves.
+         */
         void setMoveIntel(const Intelligence moveIntel);
+        /**
+         * Sets the level of knowledge the trainer has about enemy items.
+         * 
+         * \param itemIntel The level of knowledge the trainer has about enemy items.
+         */
         void setItemIntel(const Intelligence itemIntel);
+        /**
+         * Sets the level of knowledge the trainer has about enemy ablities.
+         * 
+         * \param abilityIntel The level of knowledge the trainer has about enemy abilities.
+         */
         void setAbilityIntel(const Intelligence abilityIntel);
+        /**
+         * Sets the level of knowledge the trainer has about enemy stats.
+         * 
+         * \param statIntel The level of knowledge the trainer has about enemy stats.
+         */
         void setStatIntel(const Intelligence statIntel);
         
+        /**
+         * \sa setName
+         * 
+         * \return The name of the trainer class.
+         */
         QString name() const;
+        /**
+         * \sa setMoneyFactor
+         * 
+         * \return The money multiplier for the trainer class.
+         */
         int moneyFactor() const;
+        /**
+         * \sa setSkin
+         * 
+         * \return The id of the skin of the trainer class.
+         */
         int skin() const;
+        /**
+         * \sa setDepth
+         * 
+         * \return The maximum depth the AI for the trainer may think ahead.
+         */
         int depth() const;
+        /**
+         * \sa setTeamIntel
+         * 
+         * \return The level of knowledge the trainer has about enemy teams.
+         */
         Intelligence teamIntel() const;
+        /**
+         * \sa setMoveIntel
+         * 
+         * \return The level of knowledge the trainer has about enemy moves.
+         */
         Intelligence moveIntel() const;
+        /**
+         * \sa setItemIntel
+         * 
+         * \return The level of knowledge the trainer has about enemy items.
+         */
         Intelligence itemIntel() const;
+        /**
+         * \sa setAbilityIntel
+         * 
+         * \return The level of knowledge the trainer has about enemy abilities.
+         */
         Intelligence abilityIntel() const;
+        /**
+         * \sa setStatIntel
+         * 
+         * \return The level of knowledge the trainer has about enemy stats.
+         */
         Intelligence statIntel() const;
         
         bool nameCheck(const QString& name) const;