--- a/src/ai/api/ai_airport.hpp	Mon Mar 31 06:48:59 2008 +0000
+++ b/src/ai/api/ai_airport.hpp	Mon Mar 31 07:21:39 2008 +0000
@@ -19,82 +19,87 @@
 	 */
 	enum AirportType {
 		/* Note: the values _are_ important as they represent an in-game value */
-		AT_SMALL         =   0,
-		AT_LARGE         =   1,
-		AT_HELIPORT      =   2,
-		AT_METROPOLITAN  =   3,
-		AT_INTERNATIONAL =   4,
-		AT_COMMUTER      =   5,
-		AT_HELIDEPOT     =   6,
-		AT_INTERCON      =   7,
-		AT_HELISTATION   =   8,
+		AT_SMALL         =   0, //!< The small airport.
+		AT_LARGE         =   1, //!< The large airport.
+		AT_METROPOLITAN  =   3, //!< The metropolitan airport.
+		AT_INTERNATIONAL =   4, //!< The international airport.
+		AT_COMMUTER      =   5, //!< The commuter airport.
+		AT_INTERCON      =   7, //!< The intercontinental airport.
+
+		/* Next are the airports which only have helicopter platforms */
+		AT_HELIPORT      =   2, //!< The heliport.
+		AT_HELISTATION   =   8, //!< The helistation.
+		AT_HELIDEPOT     =   6, //!< The helidepot.
 	};
 
 	/**
 	 * Checks whether the given tile is actually a tile with a hangar.
-	 * @param tile the tile to check.
+	 * @param tile The tile to check.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @return true if and only if the tile has a hangar.
+	 * @return True if and only if the tile has a hangar.
 	 */
 	static bool IsHangarTile(TileIndex tile);
 
 	/**
 	 * Checks whether the given tile is actually a tile with a airport.
-	 * @param tile the tile to check.
+	 * @param tile The tile to check.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @return true if and only if the tile has a airport.
+	 * @return True if and only if the tile has a airport.
 	 */
 	static bool IsAirportTile(TileIndex tile);
 
 	/**
 	 * Check if a certain airport type is already available.
-	 * @param type the type of airport to check.
+	 * @param type The type of airport to check.
 	 */
 	static bool AirportAvailable(AirportType type);
 
 	/**
 	 * Get the width of this type of airport.
-	 * @param type the type of airport.
-	 * @return the width in tiles.
+	 * @param type The type of airport.
+	 * @return The width in tiles.
 	 */
 	static int32 GetAirportWidth(AirportType type);
 
 	/**
 	 * Get the height of this type of airport.
-	 * @param type the type of airport.
-	 * @return the height in tiles.
+	 * @param type The type of airport.
+	 * @return The height in tiles.
 	 */
 	static int32 GetAirportHeight(AirportType type);
 
 	/**
 	 * Get the coverage radius of this type of airport.
-	 * @param type the type of airport.
-	 * @return the radius in tiles.
+	 * @param type The type of airport.
+	 * @return The radius in tiles.
 	 */
 	static int32 GetAirportCoverageRadius(AirportType type);
 
 	/**
 	 * Get the first hanger tile of the airport.
-	 * @param tile any tile of the airport.
+	 * @param tile Any tile of the airport.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @return the first hanger tile of the airport.
+	 * @return The first hanger tile of the airport.
+	 * @note Possible there are more hangars, but you won't be able to find them
+	 *  without walking over all the tiles of the airport and using
+	 *  IsHangarTile() on them.
 	 */
 	static TileIndex GetHangarOfAirport(TileIndex tile);
 
 	/**
 	 * Builds a airport with tile at the topleft corner.
-	 * @param tile the topleft corner of the airport.
-	 * @param type the type of airport to build.
+	 * @param tile The topleft corner of the airport.
+	 * @param type The type of airport to build.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @return whether the airport has been/can be build or not.
+	 * @return Whether the airport has been/can be build or not.
 	 */
 	static bool BuildAirport(TileIndex tile, AirportType type);
 
 	/**
 	 * Removes a airport.
-	 * @param tile any tile of the airport.
+	 * @param tile Any tile of the airport.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @return whether the airport has been/can be removed or not.
+	 * @return Whether the airport has been/can be removed or not.
 	 */
 	static bool RemoveAirport(TileIndex tile);
 };

--- a/src/ai/api/ai_base.hpp	Mon Mar 31 06:48:59 2008 +0000
+++ b/src/ai/api/ai_base.hpp	Mon Mar 31 07:21:39 2008 +0000
@@ -11,12 +11,10 @@
  * 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.
- *       However, because in MP we cannot use Random because that will cause
- *       desyncs (AIs are ran locally, not on all clients). This means that
- *       we use InteractiveRandom in MP, thus the whole random debugging is
- *       pointless for the AIs. Therefor the random functions are called
- *       differently.
+ *        RANDOM_DEBUG does some tricky stuff, which messes with those names.
+ * @note In MP we cannot use Random because that will cause desyncs (AIs are
+ *        ran on the server only, not on all clients). This means that
+ *        we use InteractiveRandom in MP. Rand() takes care of this for you.
  */
 class AIBase : public AIObject {
 public:
@@ -24,38 +22,38 @@
 
 	/**
 	 * Get a random value.
-	 * @return a random value between 0 and MAX(uint32).
+	 * @return A random value between 0 and MAX(uint32).
 	 */
 	static uint32 Rand();
 
 	/**
 	 * Get a random value.
 	 * @param unused_param This param is not used, but is needed to work with lists.
-	 * @return a random value between 0 and MAX(uint32).
+	 * @return A random value between 0 and MAX(uint32).
 	 */
 	static uint32 RandItem(int unused_param);
 
 	/**
 	 * 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.
 	 */
 	static uint RandRange(uint max);
 
 	/**
 	 * Get a random value in a range.
 	 * @param unused_param This param is not used, but is needed to work with lists.
-	 * @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.
 	 */
 	static uint RandRangeItem(int unused_param, uint max);
 
 	/**
 	 * Returns approximatelly 'out' times true when called 'max' times.
 	 *   After all, it is a random function.
-	 * @param out how many times it should return true.
-	 * @param max out of this many times.
-	 * @return true if the chance worked out.
+	 * @param out How many times it should return true.
+	 * @param max Out of this many times.
+	 * @return True if the chance worked out.
 	 */
 	static bool Chance(uint out, uint max);
 
@@ -63,9 +61,9 @@
 	 * Returns approximatelly 'out' times true when called 'max' times.
 	 *   After all, it is a random function.
 	 * @param unused_param This param is not used, but is needed to work with lists.
-	 * @param out how many times it should return true.
-	 * @param max out of this many times.
-	 * @return true if the chance worked out.
+	 * @param out How many times it should return true.
+	 * @param max Out of this many times.
+	 * @return True if the chance worked out.
 	 */
 	static bool ChanceItem(int unused_param, uint out, uint max);
 };

--- a/src/ai/api/ai_bridge.hpp	Mon Mar 31 06:48:59 2008 +0000
+++ b/src/ai/api/ai_bridge.hpp	Mon Mar 31 07:21:39 2008 +0000
@@ -28,9 +28,9 @@
 
 	/**
 	 * Checks whether the given tile is actually a bridge start or end tile.
-	 * @param tile the tile to check.
+	 * @param tile The tile to check.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @return true if and only if the tile is the beginning or end of a bridge.
+	 * @return True if and only if the tile is the beginning or end of a bridge.
 	 */
 	static bool IsBridgeTile(TileIndex tile);
 
@@ -39,7 +39,6 @@
 	 * @param bridge_id The bridge to get the name of.
 	 * @pre IsValidBridge(bridge_id).
 	 * @return The name the bridge has.
-	 * @note the returned name must be free'd (C++ only).
 	 */
 	static char *GetName(BridgeID bridge_id);
 
@@ -78,10 +77,10 @@
 
 	/**
 	 * Get the year in which a bridge becomes available.
-	 * @note Years are like 2010, -10 (10 B.C.), 1950, ..
 	 * @param bridge_id The bridge to get the year of availability of.
 	 * @pre IsValidBridge(bridge_id).
 	 * @returns The year of availability the bridge has.
+	 * @note Years are like 2010, -10 (10 B.C.), 1950, ..
 	 */
 	static int32 GetYearAvailable(BridgeID bridge_id);
 
@@ -93,10 +92,10 @@
 	 * @param end Where to end the bridge.
 	 * @pre AIMap::IsValidTile(start).
 	 * @pre AIMap::IsValidTile(end).
-	 * @pre start and end are in a straight line, i.e.
+	 * @pre 'start' and 'end' are in a straight line, i.e.
 	 *  AIMap::GetTileX(start) == AIMap::GetTileX(end) or
 	 *  AIMap::GetTileY(start) == AIMap::GetTileY(end).
-	 * @pre vehicleType is either AIVehicle::VEHICLE_RAIL or AIVEHICLE::VEHICLE_ROAD.
+	 * @pre VehicleType is either AIVehicle::VEHICLE_RAIL or AIVEHICLE::VEHICLE_ROAD.
 	 * @return Whether the bridge has been/can be build or not.
 	 */
 	static bool BuildBridge(AIVehicle::VehicleType vehicle_type, BridgeID bridge_id, TileIndex start, TileIndex end);

--- a/src/ai/api/ai_cargo.hpp	Mon Mar 31 06:48:59 2008 +0000
+++ b/src/ai/api/ai_cargo.hpp	Mon Mar 31 07:21:39 2008 +0000
@@ -16,33 +16,34 @@
 
 	/**
 	 * Checks whether the given cargo type is valid.
-	 * @param cargo_type the cargo to check.
-	 * @return true if and only if the cargo type is valid.
+	 * @param cargo_type The cargo to check.
+	 * @return True if and only if the cargo type is valid.
 	 */
 	static bool IsValidCargo(CargoID cargo_type);
 
 	/**
 	 * 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).
+	 * @param cargo_type The cargo to get the string representation of.
+	 * @return The cargo label.
+	 * @note Never use this to check if it is a certain cargo. NewGRF can
+	 *  redefine all of the names.
 	 */
 	static char *GetCargoLabel(CargoID cargo_type);
 
 	/**
 	 * 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.
+	 * @param cargo_type The cargo to check on.
+	 * @return True if and only if the cargo is freight.
 	 */
 	static bool IsFreight(CargoID cargo_type);
 
 	/**
 	 * Get the income for transporting a piece of cargo over the
 	 *   given distance within the specified time.
-	 * @param cargo_type the cargo to transport.
-	 * @param distance the distance the cargo travels from begin to end.
-	 * @param days_in_transit amount of (game) days the cargo is in transit.
-	 * @return the amount of money that would be earned by this trip.
+	 * @param cargo_type The cargo to transport.
+	 * @param distance The distance the cargo travels from begin to end.
+	 * @param days_in_transit Amount of (game) days the cargo is in transit.
+	 * @return The amount of money that would be earned by this trip.
 	 */
 	static int32 GetCargoIncome(CargoID cargo_type, uint32 distance, uint32 days_in_transit);
 };

--- a/src/ai/api/ai_company.hpp	Mon Mar 31 06:48:59 2008 +0000
+++ b/src/ai/api/ai_company.hpp	Mon Mar 31 07:21:39 2008 +0000
@@ -14,130 +14,126 @@
 public:
 	static const char *GetClassName() { return "AICompany"; }
 
-	/** Different constants related to companies */
+	/** Different constants related to CompanyIndex. */
 	enum CompanyIndex {
 		FIRST_COMPANY   = 0, ///< The first available company.
 		LAST_COMPANY    = 7, ///< The last available company.
 		MY_COMPANY      = 8, ///< Constant that gets resolved to the correct company index for your company.
-		INVALID_COMPANY = 9, ///< An invalid company
+		INVALID_COMPANY = 9, ///< An invalid company.
 	};
 
 	/**
-	 * Resolved the given company index to the correct index
-	 * for the company. If the company index was MY_COMPANY
-	 * it will be resolved to the index of your company.
-	 * If the company with the given index does not exist
-	 * it will return INVALID_COMPANY.
-	 * @param company the company index to resolve.
-	 * @return the resolved company index.
+	 * Resolved the given company index to the correct index for the company. If
+	 *  the company index was MY_COMPANY it will be resolved to the index of
+	 *  your company. If the company with the given index does not exist it will
+	 *  return INVALID_COMPANY.
+	 * @param company The company index to resolve.
+	 * @return The resolved company index.
 	 */
 	static CompanyIndex ResolveCompanyIndex(CompanyIndex company);
 
 	/**
 	 * Set the name of your company.
-	 * @param name the new name of the company.
-	 * @pre name != NULL
-	 * @return true if the name was changed.
+	 * @param name The new name of the company.
+	 * @return True if the name was changed.
 	 */
 	static bool SetCompanyName(const char *name);
 
 	/**
 	 * Get the name of the given company.
-	 * @param company the company to get the name for.
+	 * @param company The company to get the name for.
 	 * @pre ResolveCompanyIndex(company) != INVALID_COMPANY
-	 * @return the name of the given company.
-	 * @note the returned company name must be free'd (C++ only).
+	 * @return The name of the given company.
 	 */
 	static char *GetCompanyName(CompanyIndex company);
 
 	/**
 	 * Set the name of your president.
-	 * @param name the new name of the president.
-	 * @pre name != NULL
-	 * @return true if the name was changed.
+	 * @param name The new name of the president.
+	 * @return True if the name was changed.
 	 */
 	static bool SetPresidentName(const char *name);
 
 	/**
 	 * Get the name of the president of the given company.
-	 * @param company the company to get the president's name for.
+	 * @param company The company to get the president's name for.
 	 * @pre ResolveCompanyIndex(company) != INVALID_COMPANY
-	 * @return the name of the president of the given company.
-	 * @note the returned president name must be free'd (C++ only).
+	 * @return The name of the president of the given company.
 	 */
 	static char *GetPresidentName(CompanyIndex company);
 
 	/**
 	 * Sets the amount to loan.
-	 * @param loan the amount to loan (multiplier of GetLoanInterval()).
-	 * @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 non-negative.
-	 * @return true if the loan could be set to your requested amount.
+	 * @param loan The amount to loan (multiplier of GetLoanInterval()).
+	 * @pre 'loan' must be non-negative.
+	 * @pre GetLoanInterval() must be a multiplier of GetLoanInterval().
+	 * @pre 'loan' must be below GetMaxLoanAmount().
+	 * @pre 'loan' - GetLoanAmount() + GetBankBalance() must be non-negative.
+	 * @return True if the loan could be set to your requested amount.
 	 */
 	static bool SetLoanAmount(int32 loan);
 
 	/**
 	 * Sets the minimum amount to loan, i.e. the given amount of loan rounded up.
-	 * @param loan the amount to loan (any positive number).
-	 * @pre loan must be non-negative.
-	 * @pre loan must be below GetMaxLoan().
-	 * @return true if we could allocate a minimum of "loan" loan.
+	 * @param loan The amount to loan (any positive number).
+	 * @pre 'loan' must be non-negative.
+	 * @pre 'loan' must be below GetMaxLoanAmount().
+	 * @return True if we could allocate a minimum of "loan" loan.
 	 */
 	static bool SetMinimumLoanAmount(int32 loan);
 
 	/**
 	 * Gets the amount your company have loaned.
-	 * @return the amount loaned money.
-	 * @post the return value is always non-negative.
+	 * @return The amount loaned money.
+	 * @post The return value is always non-negative.
 	 * @post GetLoanInterval() is always a multiplier of the return value.
 	 */
 	static int32 GetLoanAmount();
 
 	/**
 	 * Gets the maximum amount your company can loan.
-	 * @return the maximum amount your company can loan.
-	 * @post the return value is always non-negative.
+	 * @return The maximum amount your company can loan.
+	 * @post The return value is always non-negative.
 	 * @post GetLoanInterval() is always a multiplier of the return value.
 	 */
 	static int32 GetMaxLoanAmount();
 
 	/**
 	 * Gets the interval/loan step.
-	 * @return the loan step.
-	 * @post return value is always positive.
+	 * @return The loan step.
+	 * @post Return value is always positive.
 	 */
 	static int32 GetLoanInterval();
 
 	/**
 	 * Gets the current value of the given company.
-	 * @param company the company to get the company value of.
+	 * @param company The company to get the company value of.
 	 * @pre ResolveCompanyIndex(company) != INVALID_COMPANY
-	 * @return the current value of the given company.
+	 * @return The current value of the given company.
 	 */
 	static int32 GetCompanyValue(CompanyIndex company);
 
 	/**
 	 * Gets the bank balance. In other words, the amount of money the given company can spent.
-	 * @param company the company to get the bank balance of.
+	 * @param company The company to get the bank balance of.
 	 * @pre ResolveCompanyIndex(company) != INVALID_COMPANY
-	 * @return the actual bank balance.
+	 * @return The actual bank balance.
 	 */
 	static int32 GetBankBalance(CompanyIndex company);
 
 	/**
 	 * Build your company's HQ on the given tile.
-	 * @param tile the tile to build your HQ on, this tile is the most nothern tile of your HQ.
+	 * @param tile The tile to build your HQ on, this tile is the most nothern tile of your HQ.
 	 * @pre AIMap::IsValidTile(tile).
-	 * @note An HQ can not be removed, only by water or rebuilding; If an HQ is build again, the old one is removed.
-	 * @return true if the HQ could be build.
+	 * @return True if the HQ could be build.
+	 * @note An HQ can not be removed, only by water or rebuilding; If an HQ is
+	 *  build again, the old one is removed.
 	 */
 	static bool BuildCompanyHQ(TileIndex tile);
 
 	/**
 	 * Return the location of a company's HQ.
-	 * @param company the company the get the HQ of.
+	 * @param company The company the get the HQ of.
 	 * @pre ResolveCompanyIndex(company) != INVALID_COMPANY.
 	 * @return The tile of the company's HQ, this tile is the most nothern tile of that HQ, or INVALID_TILE if there is no HQ yet.
 	 */

--- a/src/ai/api/ai_date.hpp	Mon Mar 31 06:48:59 2008 +0000
+++ b/src/ai/api/ai_date.hpp	Mon Mar 31 07:21:39 2008 +0000
@@ -24,39 +24,39 @@
 	/**
 	 * Get the current date.
 	 * This is the number of days since epoch under the assumption that
-	 * there is a leap year every 4 years, except when dividable by
-	 * 100 but not by 400.
-	 * @return a date.
+	 *  there is a leap year every 4 years, except when dividable by
+	 *  100 but not by 400.
+	 * @return The current date.
 	 */
 	static int32 GetCurrentDate();
 
 	/**
 	 * Get the year of the given date.
-	 * @param date the date to get the year of.
-	 * @return the year.
+	 * @param date The date to get the year of.
+	 * @return The year.
 	 */
 	static int32 GetYear(int32 date);
 
 	/**
 	 * Get the month of the given date.
-	 * @param date the date to get the month of.
-	 * @return the month.
+	 * @param date The date to get the month of.
+	 * @return The month.
 	 */
 	static int32 GetMonth(int32 date);
 
 	/**
 	 * Get the day (of the month) of the given date.
-	 * @param date the date to get the day of.
-	 * @return the day.
+	 * @param date The date to get the day of.
+	 * @return The day.
 	 */
 	static int32 GetDayOfMonth(int32 date);
 
 	/**
 	 * Get the date given a year, month and day of month.
-	 * @param year the year of the to-be determined date.
-	 * @param month the month of the to-be determined date.
-	 * @param day_of_month the day of month of the to-be determined date.
-	 * @return the date.
+	 * @param year The year of the to-be determined date.
+	 * @param month The month of the to-be determined date.
+	 * @param day_of_month The day of month of the to-be determined date.
+	 * @return The date.
 	 */
 	static int32 GetDate(int32 year, int32 month, int32 day_of_month);
 };