Codechange: add missing documentation

src/engine.cpp

@@ -591,6 +591,14 @@ EngineID EngineOverrideManager::UseUnreservedID(VehicleType type, uint16_t grf_l
 	return it->engine;
 }
 
+/**
+ * Create an override to the given engine. If the override already exists, it will be overwritten.
+ * @param type The vehicle type.
+ * @param grf_local_id The NewGRF internal identifier.
+ * @param grfid The unique identifier of the NewGRF.
+ * @param substitute_id The fallback original engine.
+ * @param engine The engine this override is for.
+ */
 void EngineOverrideManager::SetID(VehicleType type, uint16_t grf_local_id, GrfID grfid, uint8_t substitute_id, EngineID engine)
 {
 	auto &map = this->mappings[type];

src/engine_base.h

@@ -207,11 +207,31 @@ struct EngineIDMapping {
 	uint8_t substitute_id = 0; ///< The (original) entity ID to use if this GRF is not available (currently not used)
 	EngineID engine{};
 
+	/**
+	 * Create a 64 bit key from the GRFID and internal ID for mappings.
+	 * @param grfid The NewGRF id.
+	 * @param internal_id The internal ID within the GRF file.
+	 * @return The key.
+	 */
 	static inline uint64_t Key(GrfID grfid, uint16_t internal_id) { return static_cast<uint64_t>(grfid) << 32 | internal_id; }
 
+	/**
+	 * Create a 64 bit key from this mapping.
+	 * @return The key.
+	 */
 	inline uint64_t Key() const { return Key(this->grfid, this->internal_id); }
 
+	/** Create a new mapping. */
 	EngineIDMapping() {}
+
+	/**
+	 * Create the mapping.
+	 * @param grfid The unique identifer of the NewGRF.
+	 * @param internal_id The internal identifier of the engine within the NewGRF.
+	 * @param type The vehicle type.
+	 * @param substitute_id The original vehicle to fall back to.
+	 * @param engine The engine the mapping is for.
+	 */
 	EngineIDMapping(GrfID grfid, uint16_t internal_id, VehicleType type, uint8_t substitute_id, EngineID engine)
 		: grfid(grfid), internal_id(internal_id), type(type), substitute_id(substitute_id), engine(engine) {}
 };

src/newgrf/newgrf_actd.cpp

@@ -132,6 +132,15 @@ static uint32_t GetPatchVariable(uint8_t param)
 	}
 }
 
+/**
+ * Performs the GRF Resource Management, where NewGRFs can cooperatively manage sprite resources.
+ * @param grm Mapping to the NewGRF linked with a resource.
+ * @param count The number of elements to process.
+ * @param op The operation to perform.
+ * @param target The target for the operation.
+ * @param type Name of type for debug messages.
+ * @return Operation/target specific result.
+ */
 static uint32_t PerformGRM(std::span<GrfID> grm, uint16_t count, uint8_t op, uint8_t target, std::string_view type)
 {
 	uint start = 0;

src/newgrf_house.cpp

@@ -136,6 +136,12 @@ void ResetHouseClassIDs()
 	_class_mapping.emplace_back();
 }
 
+/**
+ * Allocate a house class for the given NewGRF and ID.
+ * @param grf_class_id The class id within the NewGRF.
+ * @param grfid The GRF this class belongs to.
+ * @return The existing allocation, or a new one when it did not exist yet.
+ */
 HouseClassID AllocateHouseClassID(uint8_t grf_class_id, GrfID grfid)
 {
 	/* Start from 1 because 0 means that no class has been assigned. */

src/newgrf_storage.h

@@ -198,6 +198,13 @@ extern PersistentStoragePool _persistent_storage_pool;
  * Class for pooled persistent storage of data.
  */
 struct PersistentStorage : PersistentStorageArray<int32_t, 256>, PersistentStoragePool::PoolItem<&_persistent_storage_pool> {
+	/**
+	 * Create the pooled storage.
+	 * @param index The unique identifier of the pool item.
+	 * @param grfid The NewGRF this storage is of.
+	 * @param feature The feature associated with this storage.
+	 * @param tile The tile associated with this storage.
+	 */
 	PersistentStorage(PersistentStorageID index, GrfID grfid, GrfSpecFeature feature, TileIndex tile) : PersistentStoragePool::PoolItem<&_persistent_storage_pool>(index)
 	{
 		this->grfid = grfid;

src/newgrf_townname.cpp

@@ -24,6 +24,11 @@
 static std::vector<GRFTownName> _grf_townnames;
 static std::vector<StringID> _grf_townname_names;
 
+/**
+ * Get the \c GRFTownName for the given GRFID.
+ * @param grfid The GRFID of the town name.
+ * @return The \c GRFTownName or \c nullptr if it does not exist.
+ */
 GRFTownName *GetGRFTownName(GrfID grfid)
 {
 	auto found = std::ranges::find(_grf_townnames, grfid, &GRFTownName::grfid);
@@ -31,6 +36,11 @@ GRFTownName *GetGRFTownName(GrfID grfid)
 	return nullptr;
 }
 
+/**
+ * Get the \c GRFTownName for the given GRFID or allocate one if it does not exist.
+ * @param grfid The GRFID of the town name.
+ * @return The \c GRFTownName.
+ */
 GRFTownName *AddGRFTownName(GrfID grfid)
 {
 	GRFTownName *t = GetGRFTownName(grfid);
@@ -41,6 +51,10 @@ GRFTownName *AddGRFTownName(GrfID grfid)
 	return t;
 }
 
+/**
+ * Remove the \c GRFTownName mapping for the given GRFID.
+ * @param grfid The NewGRF to remove for.
+ */
 void DelGRFTownName(GrfID grfid)
 {
 	_grf_townnames.erase(std::ranges::find(_grf_townnames, grfid, &GRFTownName::grfid));
@@ -66,6 +80,13 @@ static void RandomPart(StringBuilder &builder, const GRFTownName *t, uint32_t se
 	}
 }
 
+/**
+ * Construct a NewGRF town name into the builder.
+ * @param builder The string builder to write to.
+ * @param grfid The NewGRF providing the information/logic.
+ * @param gen The town name style to get from the NewGRF.
+ * @param seed The random 32 bit number to generate the town name for.
+ */
 void GRFTownNameGenerate(StringBuilder &builder, GrfID grfid, uint16_t gen, uint32_t seed)
 {
 	const GRFTownName *t = GetGRFTownName(grfid);