--- a/src/ai/api/ai_company.hpp	Sat Mar 17 23:02:33 2007 +0000
+++ b/src/ai/api/ai_company.hpp	Sun Mar 18 00:00:51 2007 +0000
@@ -42,7 +42,7 @@
 	/**
 	 * Gets the amount your company have loaned.
 	 * @return the amount loaned money.
-	 * @post the return value is always positive.
+	 * @post the return value is always non-negative.
 	 * @post GetLoanInterval() is always a multiplier of the return value.
 	 */
 	int32 GetLoanAmount();
@@ -50,7 +50,7 @@
 	/**
 	 * Gets the maximum amount your company can loan.
 	 * @return the maximum amount your company can loan.
-	 * @post the return value is always positive.
+	 * @post the return value is always non-negative.
 	 * @post GetLoanInterval() is always a multiplier of the return value.
 	 */
 	int32 GetMaxLoanAmount();
@@ -65,10 +65,10 @@
 	/**
 	 * Sets the amount to loan.
 	 * @param loan the amount to loan (multiplier of GetLoanInterval()).
-	 * @pre loan must be positive.
+	 * @pre loan must be non-negative.
 	 * @pre GetLoanInterval must be a multiplier of loan.
 	 * @pre loan must be below GetMaxLoan().
-	 * @pre loan - GetLoanAmount() + GetBankBalance() must be positive.
+	 * @pre loan - GetLoanAmount() + GetBankBalance() must be non-negative.
 	 * @return true if the loan could be set to your requested amount.
 	 */
 	bool SetLoanAmount(int32 loan);

--- a/src/ai/api/ai_controller.hpp	Sat Mar 17 23:02:33 2007 +0000
+++ b/src/ai/api/ai_controller.hpp	Sun Mar 18 00:00:51 2007 +0000
@@ -7,45 +7,67 @@
 
 #include "../../stdafx.h"
 
+/**
+ * Class that handles the core of every AI. Each AI needs to extend this class
+ *  in order to work. The OpenTTD core makes sure GetTick gets increased when
+ *  needed.
+ */
 class AIController {
 private:
 	uint tick;
 
 public:
+	/**
+	 * Initializer of the AIController.
+	 */
 	AIController() :
 		tick(0)
 	{}
 
+	/**
+	 * Destructor of the AIController.
+	 */
 	virtual ~AIController() { }
 
 	/**
-	 * This function is called once to start the AI.
+	 * This function is called to start your AI. Your AI starts here. If you
+	 *   return from this function, your AI dies, so make sure that doesn't
+	 *   happen. It is okay to use while() {} loops, as long as you put a
+	 *   Sleep() in it to give the rest of the game time to do things. Also
+	 *   don't keep the system busy for too long, as people will consider
+	 *   that annoying.
+	 * @note Cannot be called from within your AI.
 	 */
 	virtual void Start() = 0;
 
 	/**
-	 * When this function is called, the AI must stop
-	 * as soon as possible. It may not call any function
-	 * that might suspend, like DoCommand and Sleep.
-	 * @note This is only called when the AI is currently
-	 *       in a suspended state.
+	 * When this function is called, the AI must stop as soon as possible.
+	 *   It may not call any function that might suspend, like DoCommand()
+	 *   and Sleep().
+	 * @note Cannot be called from within your AI.
 	 */
 	virtual void Stop() = 0;
 
 	/**
-	 * Increase the internal ticker.
+	 * Increase the internal ticker. You should never call this yourself,
+	 *   as it is called by the OpenTTD system itself.
+	 * @note Cannot be called from within your AI.
 	 */
 	void IncreaseTick() { this->tick++; }
 
 	/**
-	 * Return the value of the ticker.
+	 * Find at which tick your AI currently is.
+	 * @return returns the current tick.
 	 */
 	uint GetTick() { return this->tick; }
 
 	/**
 	 * Sleep for X ticks. The code continues after this line when the X AI ticks
-	 *  are passed. Mind that an AI tick is different from in-game ticks and
-	 *  differ per AI speed.
+	 *   are passed. Mind that an AI tick is different from in-game ticks and
+	 *   differ per AI speed.
+	 * @param ticks the ticks to wait
+	 * @post the value of GetTick() will be changed exactly 'ticks' in value after
+	 *   calling this.
 	 */
 	void Sleep(uint ticks);
 };

--- a/src/ai/api/ai_industry.hpp	Sat Mar 17 23:02:33 2007 +0000
+++ b/src/ai/api/ai_industry.hpp	Sun Mar 18 00:00:51 2007 +0000
@@ -7,44 +7,49 @@
 
 #include "ai_object.hpp"
 
+/**
+ * Class that handles all industry related functions.
+ */
 class AIIndustry : public AIObject {
 public:
 	/**
-	 * Gets the maximum industry index; there are no valid industries with a higher index
-	 * @return the maximum town index
-	 * @post return >= 0
+	 * Gets the maximum industry index; there are no valid industries with a
+	 *   higher index.
+	 * @return the maximum industry index.
+	 * @post return value is always non-negative.
 	 */
 	IndustryID GetMaxIndustryID();
 
 	/**
-	 * Gets the number of industries
-	 * @return the number of industries
-	 * @post return >= 0
+	 * Gets the number of industries. This is different than GetMaxIndustryID()
+	 *   because of the way OpenTTD works internally.
+	 * @return the number of industries.
+	 * @post return value is always non-negative.
 	 */
 	int32 GetIndustryCount();
 
 	/**
-	 * Checks whether the given industry index is valid
-	 * @param industry_id the index to check
-	 * @return true if and only if the industry is valid
+	 * Checks whether the given industry index is valid.
+	 * @param industry_id the index to check.
+	 * @return true if and only if the industry is valid.
 	 */
 	bool IsValidIndustry(IndustryID industry_id);
 
 	/**
-	 * Get the name of the industry
-	 * @param industry_id the industry to get the name of
-	 * @pre this->IsValidIndustry(industry_id)
-	 * @return the name of the industry
-	 * @note the returned name must be freed
+	 * Get the name of the industry.
+	 * @param industry_id the industry to get the name of.
+	 * @pre industry_id has to be valid (use IsValidIndustry()).
+	 * @return the name of the industry.
+	 * @note the returned name must be free'd (C++ only).
 	 */
 	char *GetName(IndustryID industry_id);
 
 	/**
-	 * Gets the location of the industry
-	 * @param industry_id the location of the industry
-	 * @pre this->IsValidIndustry(industry_id)
-	 * @return the location of the industry
-	 * @post return >= 0
+	 * Gets the location of the industry.
+	 * @param industry_id the location of the industry.
+	 * @pre industry_id has to be valid (use IsValidIndustry()).
+	 * @return the location of the industry.
+	 * @post return value is always positive and below AIMap::GetMapSize().
 	 */
 	TileIndex GetLocation(IndustryID industry_id);
 };

--- a/src/ai/api/ai_map.hpp	Sat Mar 17 23:02:33 2007 +0000
+++ b/src/ai/api/ai_map.hpp	Sun Mar 18 00:00:51 2007 +0000
@@ -7,51 +7,54 @@
 
 #include "ai_object.hpp"
 
+/**
+ * Class that handles all map related functions.
+ */
 class AIMap : public AIObject {
 public:
 	/**
-	 * Checks whether the given tile is valid
-	 * @param t the tile to check
-	 * @return true is the tile it within the boundaries of the map
+	 * Checks whether the given tile is valid.
+	 * @param t the tile to check.
+	 * @return true is the tile it within the boundaries of the map.
 	 */
 	bool IsValidTile(TileIndex t);
 
 	/**
-	 * Gets the number of tiles in the map
-	 * @return the size of the map in tiles
-	 * @post return > 0
+	 * Gets the number of tiles in the map.
+	 * @return the size of the map in tiles.
+	 * @post return value is always positive.
 	 */
 	TileIndex GetMapSize();
 
 	/**
-	 * Gets the amount of tiles along the SW and NE border
-	 * @return the length along the SW and NE borders
-	 * @post return > 0
+	 * Gets the amount of tiles along the SW and NE border.
+	 * @return the length along the SW and NE borders.
+	 * @post return value is always positive.
 	 */
 	uint32 GetMapSizeX();
 
 	/**
-	 * Gets the amount of tiles along the SE and NW border
-	 * @return the length along the SE and NW borders
-	 * @post return > 0
+	 * Gets the amount of tiles along the SE and NW border.
+	 * @return the length along the SE and NW borders.
+	 * @post return value is always positive.
 	 */
 	uint32 GetMapSizeY();
 
 	/**
-	 * Gets the X (place along the SW/NE border)
-	 * @param t the tile to get the X of
-	 * @pre this->IsValidTile(t)
-	 * @return the x-position
-	 * @post return <= this->GetMapSizeX()
+	 * Gets the place along the SW/NE border (X-value).
+	 * @param t the tile to get the X-value of.
+	 * @pre t has to be valid (use IsValidTile(t)).
+	 * @return the X-value.
+	 * @post return value is lower than GetMapSizeX().
 	 */
 	uint32 GetTileX(TileIndex t);
 
 	/**
-	 * Gets the Y (place along the SE/NW border)
-	 * @param t the tile to get the Y of
-	 * @pre this->IsValidTile(t)
-	 * @return the y-position
-	 * @post return <= this->GetMapSizeY()
+	 * Gets the place along the SE/NW border (Y-value).
+	 * @param t the tile to get the Y-value of.
+	 * @pre t has to be valid (use IsValidTile(t)).
+	 * @return the Y-value.
+	 * @post return value is lower than GetMapSizeY().
 	 */
 	uint32 GetTileY(TileIndex t);
 };

--- a/src/ai/api/ai_object.hpp	Sat Mar 17 23:02:33 2007 +0000
+++ b/src/ai/api/ai_object.hpp	Sun Mar 18 00:00:51 2007 +0000
@@ -8,6 +8,12 @@
 #include "../../stdafx.h"
 #include "../../functions.h"
 
+/**
+ * Uper-parent object of all API classes. You should never use this class in
+ *   your AI, as it doesn't publish any public functions. It is used
+ *   internally to have a common place to handle general things, like internal
+ *   command processing, and command-validation checks.
+ */
 class AIObject {
 protected:
 	/**

--- a/src/ai/api/ai_town.hpp	Sat Mar 17 23:02:33 2007 +0000
+++ b/src/ai/api/ai_town.hpp	Sun Mar 18 00:00:51 2007 +0000
@@ -7,53 +7,57 @@
 
 #include "ai_object.hpp"
 
+/**
+ * Class that handles all town related functions.
+ */
 class AITown : public AIObject {
 public:
 	/**
-	 * Gets the maximum town index; there are no valid towns with a higher index
-	 * @return the maximum town index
-	 * @post return >= 0
+	 * Gets the maximum town index; there are no valid towns with a higher index.
+	 * @return the maximum town index.
+	 * @post return value is always non-negative.
 	 */
 	TownID GetMaxTownID();
 
 	/**
-	 * Gets the number of towns
-	 * @return the number of towns
-	 * @post return >= 0
+	 * Gets the number of towns. This is different than GetMaxTownID()
+	 *   because of the way OpenTTD works internally.
+	 * @return the number of towns.
+	 * @post return value is always non-negative.
 	 */
 	int32 GetTownCount();
 
 	/**
-	 * Checks whether the given town index is valid
-	 * @param town_id the index to check
-	 * @return true if and only if the town is valid
+	 * Checks whether the given town index is valid.
+	 * @param town_id the index to check.
+	 * @return true if and only if the town is valid.
 	 */
 	bool IsValidTown(TownID town_id);
 
 	/**
-	 * Get the name of the town
-	 * @param town_id the town to get the name of
-	 * @pre this->IsValidTown(town)
-	 * @return the name of the town
-	 * @note the returned name must be freed
+	 * Get the name of the town.
+	 * @param town_id the town to get the name of.
+	 * @pre town_id has to be valid (use IsValidTown()).
+	 * @return the name of the town.
+	 * @note the returned name must be free'd (C++ only).
 	 */
 	char *GetName(TownID town_id);
 
 	/**
-	 * Gets the number of inhabitants in the town
-	 * @param town_id the town to get the name of
-	 * @pre this->IsValidTown(town_id)
-	 * @return the number of inhabitants
-	 * @post return >= 0
+	 * Gets the number of inhabitants in the town.
+	 * @param town_id the town to get the name of.
+	 * @pre town_id has to be valid (use IsValidTown()).
+	 * @return the number of inhabitants.
+	 * @post return value is always non-negative.
 	 */
 	int32 GetPopulation(TownID town_id);
 
 	/**
-	 * Gets the location of the town
-	 * @param town_id the location of the town
-	 * @pre this->IsValidTown(town_id)
-	 * @return the location of the town
-	 * @post return >= 0
+	 * Gets the location of the town.
+	 * @param town_id the location of the town.
+	 * @pre town_id has to be valid (use IsValidTown()).
+	 * @return the location of the town.
+	 * @post return value is always positive and below AIMap::GetMapSize().
 	 */
 	TileIndex GetLocation(TownID town_id);
 };