--- a/src/ai/api/ai_base.hpp	Sat Mar 17 21:43:31 2007 +0000
+++ b/src/ai/api/ai_base.hpp	Sat Mar 17 23:02:33 2007 +0000
@@ -8,7 +8,7 @@
 #include "ai_object.hpp"
 
 /**
- * Implementation of some basic function
+ * Class that handles some basic functions.
  *
  * @note The random functions are not called Random and RandomRange, because
  *       when including them the RANDOM_DEBUG stuff messes with their names.
@@ -22,22 +22,21 @@
 public:
 	/**
 	 * Get a random value.
-	 * @return A random value between 0 and MAX(uint32)
+	 * @return a random value between 0 and MAX(uint32).
 	 */
 	uint32 Rand();
 
 	/**
 	 * Get a random value in a range.
-	 * @param max The maximum value it will return.
-	 * @return A random value between 0 .. max.
+	 * @param max the maximum value it will return.
+	 * @return a random value between 0 .. max.
 	 */
 	uint RandRange(uint max);
 
 	/**
-	 * Take a chance of 'out' out of 'max'.
-	 * @param out How many times is should return true.
-	 * @param max What the max value of 'out' can be.
-	 * @return True if the chance worked out.
+	 * Returns approximatelly 'out' times true when called 'max' times.
+	 *   After all, it is a random function.
+	 * @return true if the chance worked out.
 	 */
 	bool Chance(uint out, uint max);
 };

--- a/src/ai/api/ai_cargo.hpp	Sat Mar 17 21:43:31 2007 +0000
+++ b/src/ai/api/ai_cargo.hpp	Sat Mar 17 23:02:33 2007 +0000
@@ -7,30 +7,33 @@
 
 #include "ai_object.hpp"
 
+/**
+ * Class that handles all cargo related functions.
+ */
 class AICargo : public AIObject {
 public:
 	/**
-	 * Gets the string representation of the cargo label
-	 * @param cargo_type to get the string representation of
-	 * @return the cargo label
-	 * @note the returned cargo label must be freed
+	 * Gets the string representation of the cargo label.
+	 * @param cargo_type to get the string representation of.
+	 * @return the cargo label.
+	 * @note the returned cargo label must be free'd (C++ only).
 	 */
 	char *GetCargoLabel(CargoID cargo_type);
 
 	/**
-	 * Checks whether the give cargo is a freight or not
+	 * Checks whether the give cargo is a freight or not.
 	 * @param cargo_type is this cargo freight or not?
-	 * @return true if and only if the cargo is freight
+	 * @return true if and only if the cargo is freight.
 	 */
 	bool IsFreight(CargoID cargo_type);
 
 	/**
 	 * Get the income for transporting a piece of cargo over the
-	 * given distance within the specified time.
-	 * @param distance        the distance the cargo travels from begin to end
-	 * @param days_in_transit amount of (game) days the cargo is in transit
-	 * @param cargo_type      the cargo to transport
-	 * @return the amount of money that would be made by this trip
+	 *   given distance within the specified time.
+	 * @param distance the distance the cargo travels from begin to end.
+	 * @param days_in_transit amount of (game) days the cargo is in transit.
+	 * @param cargo_type the cargo to transport.
+	 * @return the amount of money that would be earned by this trip.
 	 */
 	int32 GetCargoIncome(uint32 distance, uint32 days_in_transit, CargoID cargo_type);
 };

--- a/src/ai/api/ai_company.hpp	Sat Mar 17 21:43:31 2007 +0000
+++ b/src/ai/api/ai_company.hpp	Sat Mar 17 23:02:33 2007 +0000
@@ -7,66 +7,69 @@
 
 #include "ai_object.hpp"
 
+/**
+ * Class that handles all company related functions.
+ */
 class AICompany : public AIObject {
 public:
 	/**
-	 * Set the name of the company
-	 * @param name the new name of the company
+	 * Set the name of your company.
+	 * @param name the new name of the company.
 	 * @pre name != NULL
-	 * @return true if the command was send without problem
+	 * @return true if the command was send without problem.
 	 */
 	bool SetCompanyName(const char *name);
 
 	/**
-	 * Get the name of the company
-	 * @return the name of the company
-	 * @note the returned company name must be freed
+	 * Get the name of your company.
+	 * @return the name of your company.
+	 * @note the returned company name must be free'd (C++ only).
 	 */
 	char *GetCompanyName();
 
 	/**
-	 * Gets the value of the company
-	 * @return the value of the company
+	 * Gets the current value of your company.
+	 * @return the current value of your company.
 	 */
 	int32 GetCompanyValue();
 
 	/**
-	 * Gets the bank balance, i.e. the amount of money that can be spent
-	 * @return the bank balance of the company
+	 * Gets the bank balance. In other words, the amount of money you can spent.
+	 * @return the bank balance of your company.
 	 */
 	int32 GetBankBalance();
 
 	/**
-	 * Gets the amount the company have loaned
-	 * @return the amount loaned
-	 * @post return >= 0
-	 * @post return % this->GetLoanInterval() == 0
+	 * Gets the amount your company have loaned.
+	 * @return the amount loaned money.
+	 * @post the return value is always positive.
+	 * @post GetLoanInterval() is always a multiplier of the return value.
 	 */
 	int32 GetLoanAmount();
 
 	/**
-	 * Gets the maximum amount the company can loan
-	 * @return the maximum amount the company can loan
-	 * @post return >= 0
-	 * @post return % this->GetLoanInterval() == 0
+	 * Gets the maximum amount your company can loan.
+	 * @return the maximum amount your company can loan.
+	 * @post the return value is always positive.
+	 * @post GetLoanInterval() is always a multiplier of the return value.
 	 */
 	int32 GetMaxLoanAmount();
 
 	/**
-	 * Gets the interval/loan steps
-	 * @return the loan steps
-	 * @post return >= 0
+	 * Gets the interval/loan step.
+	 * @return the loan step.
+	 * @post return value is always positive.
 	 */
 	int32 GetLoanInterval();
 
 	/**
-	 * Sets the amount to loan
-	 * @param loan the amount to load (multitude of GetLoanInterval())
-	 * @pre loan >= 0
-	 * @pre loan % this->GetLoanInterval() == 0
-	 * @pre loan < GetMaxLoan()
-	 * @pre loan - GetLoan() + GetBankBalance() > 0
-	 * @return true if the command was send without a problem
+	 * Sets the amount to loan.
+	 * @param loan the amount to loan (multiplier of GetLoanInterval()).
+	 * @pre loan must be positive.
+	 * @pre GetLoanInterval must be a multiplier of loan.
+	 * @pre loan must be below GetMaxLoan().
+	 * @pre loan - GetLoanAmount() + GetBankBalance() must be positive.
+	 * @return true if the loan could be set to your requested amount.
 	 */
 	bool SetLoanAmount(int32 loan);
 };