--- 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);
 };