(svn r16510) -Doc: silence some (AI) doxygen warnings by adding comments about the appropriate things.

src/ai/api/Doxyfile

@@ -31,7 +31,6 @@ SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = YES
 QT_AUTOBRIEF           = NO
 MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 2

src/ai/api/ai_event_types.hpp

@@ -32,6 +32,7 @@ public:
 	/**
 	 * @param vehicle The vehicle that crashed.
 	 * @param crash_site Where the vehicle crashed.
+	 * @param crash_reason The reason why the vehicle crashed.
 	 */
 	AIEventVehicleCrashed(VehicleID vehicle, TileIndex crash_site, CrashReason crash_reason) :
 		AIEvent(AI_ET_VEHICLE_CRASHED),

src/ai/api/ai_object.hpp

@@ -143,9 +143,24 @@ protected:
 	 */
 	static void *&GetEventPointer();
 
+	/**
+	 * Set the cost of the last command.
+	 */
 	static void SetLastCost(Money last_cost);
+
+	/**
+	 * Get the cost of the last command.
+	 */
 	static Money GetLastCost();
+
+	/**
+	 * Set a variable that can be used by callback functions to pass information.
+	 */
 	static void SetCallbackVariable(int index, int value);
+
+	/**
+	 * Get the variable that is used by callback functions to pass information.
+	 */
 	static int GetCallbackVariable(int index);
 
 public:

src/ai/api/ai_order.hpp

@@ -288,8 +288,10 @@ public:
 	 * Sets the OrderCondition of the given order for the given vehicle.
 	 * @param vehicle_id The vehicle to set the condition type for.
 	 * @param order_position The order to set the condition type for.
+	 * @param condition The condition to compare on.
 	 * @pre IsValidVehicleOrder(vehicle_id, order_position).
 	 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
+	 * @pre condition >= OC_LOAD_PERCENTAGE && condition <= OC_UNCONDITIONALLY.
 	 * @return Whether the order has been/can be changed.
 	 */
 	static bool SetOrderCondition(VehicleID vehicle_id, OrderPosition order_position, OrderCondition condition);
@@ -298,8 +300,10 @@ public:
 	 * Sets the CompareFunction of the given order for the given vehicle.
 	 * @param vehicle_id The vehicle to set the compare function for.
 	 * @param order_position The order to set the compare function for.
+	 * @param compare The new compare function of the order.
 	 * @pre IsValidVehicleOrder(vehicle_id, order_position).
 	 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
+	 * @pre compare >= CF_EQUALS && compare <= CF_IS_FALSE.
 	 * @return Whether the order has been/can be changed.
 	 */
 	static bool SetOrderCompareFunction(VehicleID vehicle_id, OrderPosition order_position, CompareFunction compare);
@@ -308,6 +312,7 @@ public:
 	 * Sets the value to compare against of the given order for the given vehicle.
 	 * @param vehicle_id The vehicle to set the value for.
 	 * @param order_position The order to set the value for.
+	 * @param value The value to compare against.
 	 * @pre IsValidVehicleOrder(vehicle_id, order_position).
 	 * @pre order_position != ORDER_CURRENT && IsConditionalOrder(vehicle_id, order_position).
 	 * @pre value >= 0 && value < 2048.

src/ai/api/ai_station.hpp

@@ -49,6 +49,10 @@ public:
 		STATION_ANY        = 0x1F, //!< All station types
 	};
 
+	/**
+	 * Special station IDs for building adjacent/new stations when
+	 * the adjacent/distant join features are enabled.
+	 */
 	enum SpecialStationIDs {
 		STATION_NEW = 0xFFFD,           //!< Build a new station
 		STATION_JOIN_ADJACENT = 0xFFFE, //!< Join an neighbouring station if one exists

src/ai/api/ai_types.hpp

@@ -28,11 +28,11 @@
  *                           <td> creation                                          </td>
  *                           <td> deletion                                          </td>
  *                           <td> yes                                               </td></tr>
- * <tr><td>#IndustyID  </td><td> industry                                          </td>
+ * <tr><td>#IndustryID  </td><td> industry                                          </td>
  *                           <td> construction                                      </td>
  *                           <td> closure                                           </td>
  *                           <td> yes                                               </td></tr>
- * <tr><td>#IndustyType</td><td> industry type                                     </td>
+ * <tr><td>#IndustryType</td><td> industry type                                     </td>
  *                           <td> game start \ref newgrf_changes "(1)"              </td>
  *                           <td> never \ref newgrf_changes "(1)"                   </td>
  *                           <td> no                                                </td></tr>

src/ai/api/ai_vehiclelist.hpp

@@ -41,7 +41,7 @@ public:
 	static const char *GetClassName() { return "AIVehicleList_SharedOrders"; }
 
 	/**
-	 * @param station_id The vehicle that the rest shared orders with.
+	 * @param vehicle_id The vehicle that the rest shared orders with.
 	 */
 	AIVehicleList_SharedOrders(VehicleID vehicle_id);
 };

src/ai/api/ai_waypoint.hpp

@@ -15,6 +15,9 @@ class AIWaypoint : public AIObject {
 public:
 	static const char *GetClassName() { return "AIWaypoint"; }
 
+	/**
+	 * Special waypoint IDs signalling different kinds of waypoints.
+	 */
 	enum SpecialWaypointIDs {
 		WAYPOINT_INVALID = 0xFFFF, //!< An invalid WaypointID.
 	};