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

8 files changed, 85 insertions, 58 deletions

diff --git a/src/ai/api/Doxyfile b/src/ai/api/Doxyfile
index ff5d7a511..5be8606e2 100644
--- a/src/ai/api/Doxyfile
+++ b/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
diff --git a/src/ai/api/ai_event_types.hpp b/src/ai/api/ai_event_types.hpp
index 6cff88f52..3c36dfc6b 100644
--- a/src/ai/api/ai_event_types.hpp
+++ b/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),
diff --git a/src/ai/api/ai_object.hpp b/src/ai/api/ai_object.hpp
index 8fb8968c9..40f3b920c 100644
--- a/src/ai/api/ai_object.hpp
+++ b/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:
diff --git a/src/ai/api/ai_order.hpp b/src/ai/api/ai_order.hpp
index 14f20c258..c55b5e3e8 100644
--- a/src/ai/api/ai_order.hpp
+++ b/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.
diff --git a/src/ai/api/ai_station.hpp b/src/ai/api/ai_station.hpp
index 18a1d6290..783013968 100644
--- a/src/ai/api/ai_station.hpp
+++ b/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
diff --git a/src/ai/api/ai_types.hpp b/src/ai/api/ai_types.hpp
index 9653cda03..1e7812cc6 100644
--- a/src/ai/api/ai_types.hpp
+++ b/src/ai/api/ai_types.hpp
@@ -8,62 +8,62 @@
  * reused for other objects once they are released. So be careful, which IDs you store for which purpose and whether they stay valid all the time.
  *
  * <table>
- * <tr><th>type        </th><th> object                                            </th>
- *                          <th> acquired                                          </th>
- *                          <th> released                                          </th>
- *                          <th> reused                                            </th></tr>
- * <tr><td>#BridgeID   </td><td> bridge type                                       </td>
- *                          <td> introduction \ref newgrf_changes "(1)"            </td>
- *                          <td> never \ref newgrf_changes "(1)"                   </td>
- *                          <td> no \ref newgrf_changes "(1)"                      </td></tr>
- * <tr><td>#CargoID    </td><td> cargo type                                        </td>
- *                          <td> game start \ref newgrf_changes "(1)"              </td>
- *                          <td> never \ref newgrf_changes "(1)"                   </td>
- *                          <td> no \ref newgrf_changes "(1)"                      </td></tr>
- * <tr><td>#EngineID   </td><td> engine type                                       </td>
- *                          <td> introduction, preview \ref dynamic_engines "(2)"  </td>
- *                          <td> engines retires \ref dynamic_engines "(2)"        </td>
- *                          <td> no \ref dynamic_engines "(2)"                     </td></tr>
- * <tr><td>#GroupID    </td><td> vehicle group                                     </td>
- *                          <td> creation                                          </td>
- *                          <td> deletion                                          </td>
- *                          <td> yes                                               </td></tr>
- * <tr><td>#IndustyID  </td><td> industry                                          </td>
- *                          <td> construction                                      </td>
- *                          <td> closure                                           </td>
- *                          <td> yes                                               </td></tr>
- * <tr><td>#IndustyType</td><td> industry type                                     </td>
- *                          <td> game start \ref newgrf_changes "(1)"              </td>
- *                          <td> never \ref newgrf_changes "(1)"                   </td>
- *                          <td> no                                                </td></tr>
- * <tr><td>#SignID     </td><td> sign                                              </td>
- *                          <td> construction                                      </td>
- *                          <td> deletion                                          </td>
- *                          <td> yes                                               </td></tr>
- * <tr><td>#StationID  </td><td> station                                           </td>
- *                          <td> construction                                      </td>
- *                          <td> expiration of 'grey' station sign after deletion  </td>
- *                          <td> yes                                               </td></tr>
- * <tr><td>#SubsidyID  </td><td> subsidy                                           </td>
- *                          <td> offer announcement                                </td>
- *                          <td> (offer) expiration                                </td>
- *                          <td> yes                                               </td></tr>
- * <tr><td>#TileIndex  </td><td> tile on map                                       </td>
- *                          <td> game start                                        </td>
- *                          <td> never                                             </td>
- *                          <td> no                                                </td></tr>
- * <tr><td>#TownID     </td><td> town                                              </td>
- *                          <td> game start                                        </td>
- *                          <td> never                                             </td>
- *                          <td> no                                                </td></tr>
- * <tr><td>#VehicleID  </td><td> vehicle                                           </td>
- *                          <td> construction, autorenew, autoreplace              </td>
- *                          <td> destruction, autorenew, autoreplace               </td>
- *                          <td> yes                                               </td></tr>
- * <tr><td>#WaypointID </td><td> waypoint                                          </td>
- *                          <td> construction                                      </td>
- *                          <td> destruction                                       </td>
- *                          <td> yes                                               </td></tr>
+ * <tr><th>type         </th><th> object                                            </th>
+ *                           <th> acquired                                          </th>
+ *                           <th> released                                          </th>
+ *                           <th> reused                                            </th></tr>
+ * <tr><td>#BridgeID    </td><td> bridge type                                       </td>
+ *                           <td> introduction \ref newgrf_changes "(1)"            </td>
+ *                           <td> never \ref newgrf_changes "(1)"                   </td>
+ *                           <td> no \ref newgrf_changes "(1)"                      </td></tr>
+ * <tr><td>#CargoID     </td><td> cargo type                                        </td>
+ *                           <td> game start \ref newgrf_changes "(1)"              </td>
+ *                           <td> never \ref newgrf_changes "(1)"                   </td>
+ *                           <td> no \ref newgrf_changes "(1)"                      </td></tr>
+ * <tr><td>#EngineID    </td><td> engine type                                       </td>
+ *                           <td> introduction, preview \ref dynamic_engines "(2)"  </td>
+ *                           <td> engines retires \ref dynamic_engines "(2)"        </td>
+ *                           <td> no \ref dynamic_engines "(2)"                     </td></tr>
+ * <tr><td>#GroupID     </td><td> vehicle group                                     </td>
+ *                           <td> creation                                          </td>
+ *                           <td> deletion                                          </td>
+ *                           <td> yes                                               </td></tr>
+ * <tr><td>#IndustryID  </td><td> industry                                          </td>
+ *                           <td> construction                                      </td>
+ *                           <td> closure                                           </td>
+ *                           <td> yes                                               </td></tr>
+ * <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>
+ * <tr><td>#SignID      </td><td> sign                                              </td>
+ *                           <td> construction                                      </td>
+ *                           <td> deletion                                          </td>
+ *                           <td> yes                                               </td></tr>
+ * <tr><td>#StationID   </td><td> station                                           </td>
+ *                           <td> construction                                      </td>
+ *                           <td> expiration of 'grey' station sign after deletion  </td>
+ *                           <td> yes                                               </td></tr>
+ * <tr><td>#SubsidyID   </td><td> subsidy                                           </td>
+ *                           <td> offer announcement                                </td>
+ *                           <td> (offer) expiration                                </td>
+ *                           <td> yes                                               </td></tr>
+ * <tr><td>#TileIndex   </td><td> tile on map                                       </td>
+ *                           <td> game start                                        </td>
+ *                           <td> never                                             </td>
+ *                           <td> no                                                </td></tr>
+ * <tr><td>#TownID      </td><td> town                                              </td>
+ *                           <td> game start                                        </td>
+ *                           <td> never                                             </td>
+ *                           <td> no                                                </td></tr>
+ * <tr><td>#VehicleID   </td><td> vehicle                                           </td>
+ *                           <td> construction, autorenew, autoreplace              </td>
+ *                           <td> destruction, autorenew, autoreplace               </td>
+ *                           <td> yes                                               </td></tr>
+ * <tr><td>#WaypointID  </td><td> waypoint                                          </td>
+ *                           <td> construction                                      </td>
+ *                           <td> destruction                                       </td>
+ *                           <td> yes                                               </td></tr>
  * </table>
  *
  * @remarks
diff --git a/src/ai/api/ai_vehiclelist.hpp b/src/ai/api/ai_vehiclelist.hpp
index 171de7d2e..93332580b 100644
--- a/src/ai/api/ai_vehiclelist.hpp
+++ b/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);
 };
diff --git a/src/ai/api/ai_waypoint.hpp b/src/ai/api/ai_waypoint.hpp
index 9e1bec911..6762eb8f6 100644
--- a/src/ai/api/ai_waypoint.hpp
+++ b/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.
 	};