(svn r27316) -Doc: Improve documentation on ScriptCargo::GetCargoLabel

1 files changed, 9 insertions, 2 deletions

diff --git a/src/script/api/script_cargo.hpp b/src/script/api/script_cargo.hpp
index 9d409e191..d1bfdd1fc 100644
--- a/src/script/api/script_cargo.hpp
+++ b/src/script/api/script_cargo.hpp
@@ -90,8 +90,15 @@ public:
 	 * @param cargo_type The cargo to get the string representation of.
 	 * @pre ScriptCargo::IsValidCargo(cargo_type).
 	 * @return The cargo label.
-	 * @note Never use this to check if it is a certain cargo. NewGRF can
-	 *  redefine all of the names.
+	 * @note
+	 *  - The label uniquely identifies a specific cargo. Use this if you want to
+	 *    detect special cargos from specific industry set (like production booster cargos, supplies, ...).
+	 *  - For more generic cargo support, rather check cargo properties though. For example:
+	 *     - Use ScriptCargo::HasCargoClass(..., CC_PASSENGER) to decide bus vs. truck requirements.
+	 *     - Use ScriptCargo::GetTownEffect(...) paired with ScriptTown::GetCargoGoal(...) to determine
+	 *       town growth requirements.
+	 *  - In other words: Only use the cargo label, if you know more about the behaviour
+	 *    of a specific cargo from a specific industry set, than the API methods can tell you.
 	 */
 	static char *GetCargoLabel(CargoID cargo_type);