diff --git a/src/cargotype.h b/src/cargotype.h
--- a/src/cargotype.h
+++ b/src/cargotype.h
@@ -157,8 +157,18 @@ static inline bool IsCargoInClass(CargoI
 
 #define FOR_EACH_SET_CARGO_ID(var, cargo_bits) FOR_EACH_SET_BIT_EX(CargoID, var, uint, cargo_bits)
 
+/**
+ * Loop header for iterating over cargoes, sorted by name. This includes phony cargoes like regearing cargoes.
+ * @param var Reference getting the cargospec.
+ * @see CargoSpec
+ */
 #define FOR_ALL_SORTED_CARGOSPECS(var) for (uint8 index = 0; var = _sorted_cargo_specs[index], index < _sorted_cargo_specs_size; index++)
 
+/**
+ * Loop header for iterating over 'real' cargoes, sorted by name. Phony cargoes like regearing cargoes are skipped.
+ * @param var Reference getting the cargospec.
+ * @see CargoSpec
+ */
 #define FOR_ALL_SORTED_STANDARD_CARGOSPECS(var) for (uint8 index = 0; var = _sorted_cargo_specs[index], index < _sorted_standard_cargo_specs_size; index++)
 
 #endif /* CARGOTYPE_H */