(svn r24693) -Doc: Add some doxymentation into the newgrf code.

24 files changed, 276 insertions, 49 deletions

diff --git a/src/newgrf_airport.cpp b/src/newgrf_airport.cpp
index c56f097c8..4b43af483 100644
--- a/src/newgrf_airport.cpp
+++ b/src/newgrf_airport.cpp
@@ -17,6 +17,7 @@
 #include "station_base.h"
 #include "newgrf_class_func.h"
 
+/** Resolver for the airport scope. */
 struct AirportScopeResolver : public ScopeResolver {
 	struct Station *st; ///< Station of the airport for which the callback is run, or \c NULL for build gui.
 	byte airport_id;    ///< Type of airport for which the callback is run.
@@ -222,12 +223,30 @@ void AirportOverrideManager::SetEntitySpec(AirportSpec *as)
 	this->st->airport.psa->StoreValue(pos, value);
 }
 
+/**
+ * Constructor of the airport resolver.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st %Station of the airport for which the callback is run, or \c NULL for build gui.
+ * @param airport_id Type of airport for which the callback is run.
+ * @param layout Layout of the airport to build.
+ * @param callback Callback ID.
+ * @param param1 First parameter (var 10) of the callback.
+ * @param param2 Second parameter (var 18) of the callback.
+ */
 AirportResolverObject::AirportResolverObject(TileIndex tile, Station *st, byte airport_id, byte layout,
 		CallbackID callback, uint32 param1, uint32 param2)
 	: ResolverObject(AirportSpec::Get(airport_id)->grf_prop.grffile, callback, param1, param2), airport_scope(this, tile, st, airport_id, layout)
 {
 }
 
+/**
+ * Constructor of the scope resolver for an airport.
+ * @param ro Surrounding resolver.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st %Station of the airport for which the callback is run, or \c NULL for build gui.
+ * @param airport_id Type of airport for which the callback is run.
+ * @param layout Layout of the airport to build.
+ */
 AirportScopeResolver::AirportScopeResolver(ResolverObject *ro, TileIndex tile, Station *st, byte airport_id, byte layout) : ScopeResolver(ro)
 {
 	this->st = st;
diff --git a/src/newgrf_airporttiles.cpp b/src/newgrf_airporttiles.cpp
index c25d0db5f..9829286dd 100644
--- a/src/newgrf_airporttiles.cpp
+++ b/src/newgrf_airporttiles.cpp
@@ -204,12 +204,27 @@ static uint32 GetAirportTileIDAtOffset(TileIndex tile, const Station *st, uint32
 	return (this->st == NULL ? 0 : this->st->random_bits) | (this->tile == INVALID_TILE ? 0 : GetStationTileRandomBits(this->tile) << 16);
 }
 
+/**
+ * Constructor of the resolver for airport tiles.
+ * @param ats Specification of the airport tiles.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st Station of the airport for which the callback is run, or \c NULL for build gui.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 AirportTileResolverObject::AirportTileResolverObject(const AirportTileSpec *ats, TileIndex tile, Station *st,
 		CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 	: ResolverObject(ats->grf_prop.grffile, callback, callback_param1, callback_param2), tiles_scope(this, ats, tile, st)
 {
 }
 
+/**
+ * Constructor of the scope resolver specific for airport tiles.
+ * @param ats Specification of the airport tiles.
+ * @param tile %Tile for the callback, only valid for airporttile callbacks.
+ * @param st Station of the airport for which the callback is run, or \c NULL for build gui.
+ */
 AirportTileScopeResolver::AirportTileScopeResolver(ResolverObject *ro, const AirportTileSpec *ats, TileIndex tile, Station *st) : ScopeResolver(ro)
 {
 	assert(st != NULL);
diff --git a/src/newgrf_airporttiles.h b/src/newgrf_airporttiles.h
index 8daded34f..7fe57253c 100644
--- a/src/newgrf_airporttiles.h
+++ b/src/newgrf_airporttiles.h
@@ -18,8 +18,9 @@
 #include "newgrf_commons.h"
 #include "newgrf_spritegroup.h"
 
+/** Scope resolver for handling the tiles of an airport. */
 struct AirportTileScopeResolver : public ScopeResolver {
-	struct Station *st;  ///< Station of the airport for which the callback is run, or \c NULL for build gui.
+	struct Station *st;  ///< %Station of the airport for which the callback is run, or \c NULL for build gui.
 	byte airport_id;     ///< Type of airport for which the callback is run.
 	TileIndex tile;      ///< Tile for the callback, only valid for airporttile callbacks.
 
@@ -29,8 +30,9 @@ struct AirportTileScopeResolver : public ScopeResolver {
 	/* virtual */ uint32 GetVariable(byte variable, uint32 parameter, bool *available) const;
 };
 
+/** Resolver for tiles of an airport. */
 struct AirportTileResolverObject : public ResolverObject {
-	AirportTileScopeResolver tiles_scope;
+	AirportTileScopeResolver tiles_scope; ///< Scope resolver for the tiles.
 
 	AirportTileResolverObject(const AirportTileSpec *ats, TileIndex tile, Station *st,
 			CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_canal.cpp b/src/newgrf_canal.cpp
index 48c1490e6..13b7e15d6 100644
--- a/src/newgrf_canal.cpp
+++ b/src/newgrf_canal.cpp
@@ -18,8 +18,9 @@
 /** Table of canal 'feature' sprite groups */
 WaterFeature _water_feature[CF_END];
 
+/** Scope resolver of a canal tile. */
 struct CanalScopeResolver : public ScopeResolver {
-	TileIndex tile;
+	TileIndex tile; ///< Tile containing the canal.
 
 	CanalScopeResolver(ResolverObject *ro, TileIndex tile);
 
@@ -89,8 +90,12 @@ CanalScopeResolver::CanalScopeResolver(ResolverObject *ro, TileIndex tile) : Sco
 }
 
 /**
- * @param tile Tile index of canal.
+ * Canal resolver constructor.
  * @param grffile Grf file.
+ * @param tile Tile index of canal.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
  */
 CanalResolverObject::CanalResolverObject(const GRFFile *grffile, TileIndex tile,
 		CallbackID callback, uint32 callback_param1, uint32 callback_param2)
diff --git a/src/newgrf_cargo.cpp b/src/newgrf_cargo.cpp
index b084e835e..d6227b801 100644
--- a/src/newgrf_cargo.cpp
+++ b/src/newgrf_cargo.cpp
@@ -13,6 +13,7 @@
 #include "debug.h"
 #include "newgrf_spritegroup.h"
 
+/** Resolver of cargo. */
 struct CargoResolverObject : public ResolverObject {
 	CargoResolverObject(const CargoSpec *cs, CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
 
@@ -29,11 +30,23 @@ struct CargoResolverObject : public ResolverObject {
 	return NULL;
 }
 
+/**
+ * Constructor of the cargo resolver.
+ * @param cs Cargo being resolved.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 CargoResolverObject::CargoResolverObject(const CargoSpec *cs, CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 		: ResolverObject(cs->grffile, callback, callback_param1, callback_param2)
 {
 }
 
+/**
+ * Get the custom sprite for the given cargo type.
+ * @param cs Cargo being queried.
+ * @return Custom sprite to draw, or \c 0 if not available.
+ */
 SpriteID GetCustomCargoSprite(const CargoSpec *cs)
 {
 	CargoResolverObject object(cs);
diff --git a/src/newgrf_engine.cpp b/src/newgrf_engine.cpp
index 6a286f81e..05300c22b 100644
--- a/src/newgrf_engine.cpp
+++ b/src/newgrf_engine.cpp
@@ -928,6 +928,13 @@ static uint32 VehicleGetVariable(Vehicle *v, const VehicleScopeResolver *object,
 	return in_motion ? group->loaded[set] : group->loading[set];
 }
 
+/**
+ * Scope resolver of a single vehicle.
+ * @param ro Surrounding resolver.
+ * @param engine_type Engine type
+ * @param v %Vehicle being resolved.
+ * @param info_view Indicates if the item is being drawn in an info window.
+ */
 VehicleScopeResolver::VehicleScopeResolver(ResolverObject *ro, EngineID engine_type, const Vehicle *v, bool info_view)
 		: ScopeResolver(ro)
 {
@@ -947,6 +954,15 @@ static const GRFFile *GetEngineGrfFile(EngineID engine_type)
 	return (e != NULL) ? e->GetGRF() : NULL;
 }
 
+/**
+ * Resolver of a vehicle (chain).
+ * @param engine_type Engine type
+ * @param v %Vehicle being resolved.
+ * @param info_view Indicates if the item is being drawn in an info window.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 VehicleResolverObject::VehicleResolverObject(EngineID engine_type, const Vehicle *v, bool info_view,
 		CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 	: ResolverObject(GetEngineGrfFile(engine_type), callback, callback_param1, callback_param2),
diff --git a/src/newgrf_engine.h b/src/newgrf_engine.h
index 645f6310b..7eb65f134 100644
--- a/src/newgrf_engine.h
+++ b/src/newgrf_engine.h
@@ -20,10 +20,11 @@
 #include "gfx_type.h"
 #include "newgrf_spritegroup.h"
 
+/** Resolver for a vehicle scope. */
 struct VehicleScopeResolver : public ScopeResolver {
-	const struct Vehicle *v;
-	EngineID self_type;
-	bool info_view;          ///< Indicates if the item is being drawn in an info window
+	const struct Vehicle *v; ///< The vehicle being resolved.
+	EngineID self_type;      ///< Type of the vehicle.
+	bool info_view;          ///< Indicates if the item is being drawn in an info window.
 
 	VehicleScopeResolver(ResolverObject *ro, EngineID engine_type, const Vehicle *v, bool info_view);
 
@@ -35,12 +36,13 @@ struct VehicleScopeResolver : public ScopeResolver {
 	/* virtual */ void SetTriggers(int triggers) const;
 };
 
+/** Resolver for a vehicle (chain) */
 struct VehicleResolverObject : public ResolverObject {
-	VehicleScopeResolver self_scope;
-	VehicleScopeResolver parent_scope;
+	VehicleScopeResolver self_scope;     ///< Scope resolver for the indicated vehicle.
+	VehicleScopeResolver parent_scope;   ///< Scope resolver for its parent vehicle.
 
-	VehicleScopeResolver relative_scope;
-	byte cached_relative_count;
+	VehicleScopeResolver relative_scope; ///< Scope resolver for an other vehicle in the chain.
+	byte cached_relative_count;          ///< Relative position of the other vehicle.
 
 	VehicleResolverObject(EngineID engine_type, const Vehicle *v, bool info_view = false,
 			CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_generic.cpp b/src/newgrf_generic.cpp
index 9a55928cf..fe9100bba 100644
--- a/src/newgrf_generic.cpp
+++ b/src/newgrf_generic.cpp
@@ -134,11 +134,20 @@ void AddGenericCallback(uint8 feature, const GRFFile *file, const SpriteGroup *g
 	return group->loaded[0];
 }
 
-
+/**
+ * Generic resolver.
+ * @param ai_callback Callback comes from the AI.
+ * @param callback Callback ID.
+ */
 GenericResolverObject::GenericResolverObject(bool ai_callback, CallbackID callback) : ResolverObject(NULL, callback), generic_scope(this, ai_callback)
 {
 }
 
+/**
+ * Generic scope resolver.
+ * @param ro Surrounding resolver.
+ * @param ai_callback Callback comes from the AI.
+ */
 GenericScopeResolver::GenericScopeResolver(ResolverObject *ro, bool ai_callback) : ScopeResolver(ro)
 {
 	this->cargo_type = 0;
diff --git a/src/newgrf_house.cpp b/src/newgrf_house.cpp
index dd40ce8e5..0f0cc3138 100644
--- a/src/newgrf_house.cpp
+++ b/src/newgrf_house.cpp
@@ -29,7 +29,16 @@ static HouseClassMapping _class_mapping[HOUSE_CLASS_MAX];
 
 HouseOverrideManager _house_mngr(NEW_HOUSE_OFFSET, HOUSE_MAX, INVALID_HOUSE_ID);
 
-
+/**
+ * Constructor of a house scope resolver.
+ * @param ro Surrounding resolver.
+ * @param house_id Houe type being queried.
+ * @param tile %Tile containing the house.
+ * @param town %Town containing the house.
+ * @param not_yet_constructed House is still under construction.
+ * @param initial_random_bits Random bits during construction checks.
+ * @param watched_cargo_triggers Cargo types that triggered the watched cargo callback.
+ */
 HouseScopeResolver::HouseScopeResolver(ResolverObject *ro, HouseID house_id, TileIndex tile, Town *town,
 			bool not_yet_constructed, uint8 initial_random_bits, uint32 watched_cargo_triggers)
 		: ScopeResolver(ro)
@@ -53,6 +62,18 @@ static const GRFFile *GetHouseSpecGrf(HouseID house_id)
 	return (hs != NULL) ? hs->grf_prop.grffile : NULL;
 }
 
+/**
+ * Construct a resolver for a house.
+ * @param house_id House to query.
+ * @param tile %Tile containing the house.
+ * @param town %Town containing the house.
+ * @param callback Callback ID.
+ * @param param1 First parameter (var 10) of the callback.
+ * @param param2 Second parameter (var 18) of the callback.
+ * @param not_yet_constructed House is still under construction.
+ * @param initial_random_bits Random bits during construction checks.
+ * @param watched_cargo_triggers Cargo types that triggered the watched cargo callback.
+ */
 HouseResolverObject::HouseResolverObject(HouseID house_id, TileIndex tile, Town *town,
 		CallbackID callback, uint32 param1, uint32 param2,
 		bool not_yet_constructed, uint8 initial_random_bits, uint32 watched_cargo_triggers)
diff --git a/src/newgrf_house.h b/src/newgrf_house.h
index f833f96b0..d6d4beb5d 100644
--- a/src/newgrf_house.h
+++ b/src/newgrf_house.h
@@ -18,9 +18,10 @@
 #include "newgrf_spritegroup.h"
 #include "newgrf_town.h"
 
+/** Scope resolver for houses. */
 struct HouseScopeResolver : public ScopeResolver {
-	HouseID house_id;
-	TileIndex tile;
+	HouseID house_id;              ///< Type of house being queried.
+	TileIndex tile;                ///< Tile of this house.
 	Town *town;                    ///< Town of this house.
 	bool not_yet_constructed;      ///< True for construction check.
 	uint16 initial_random_bits;    ///< Random bits during construction checks.
diff --git a/src/newgrf_industries.cpp b/src/newgrf_industries.cpp
index 84f589d86..b1cb80be3 100644
--- a/src/newgrf_industries.cpp
+++ b/src/newgrf_industries.cpp
@@ -404,6 +404,16 @@ static const GRFFile *GetGrffile(IndustryType type)
 	return (indspec != NULL) ? indspec->grf_prop.grffile : NULL;
 }
 
+/**
+ * Constructor of the industries resolver.
+ * @param tile %Tile owned by the industry.
+ * @param industry %Industry being resolved.
+ * @param type Type of the industry.
+ * @param random_bits Random bits of the new industry.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 IndustriesResolverObject::IndustriesResolverObject(TileIndex tile, Industry *indus, IndustryType type, uint32 random_bits,
 		CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 	: ResolverObject(GetGrffile(type), callback, callback_param1, callback_param2),
@@ -436,6 +446,14 @@ TownScopeResolver *IndustriesResolverObject::GetTown()
 	return this->town_scope;
 }
 
+/**
+ * Scope resolver for industries.
+ * @param ro Surrounding resolver.
+ * @param tile %Tile owned by the industry.
+ * @param industry %Industry being resolved.
+ * @param type Type of the industry.
+ * @param random_bits Random bits of the new industry.
+ */
 IndustriesScopeResolver::IndustriesScopeResolver(ResolverObject *ro, TileIndex tile, Industry *industry, IndustryType type, uint32 random_bits)
 	: ScopeResolver(ro)
 {
diff --git a/src/newgrf_industries.h b/src/newgrf_industries.h
index cb1e7f21c..5c95fcdcb 100644
--- a/src/newgrf_industries.h
+++ b/src/newgrf_industries.h
@@ -14,11 +14,12 @@
 
 #include "newgrf_town.h"
 
+/** Resolver for industry scopes. */
 struct IndustriesScopeResolver : public ScopeResolver {
-	TileIndex tile;
-	Industry *industry;
-	IndustryType type;
-	uint32 random_bits;       ///< Random bits of the new industry.
+	TileIndex tile;     ///< Tile owned by the industry.
+	Industry *industry; ///< %Industry being resolved.
+	IndustryType type;  ///< Type of the industry.
+	uint32 random_bits; ///< Random bits of the new industry.
 
 	IndustriesScopeResolver(ResolverObject *ro, TileIndex tile, Industry *industry, IndustryType type, uint32 random_bits = 0);
 
@@ -29,9 +30,10 @@ struct IndustriesScopeResolver : public ScopeResolver {
 	/* virtual */ void StorePSA(uint pos, int32 value);
 };
 
+/** Resolver for industries. */
 struct IndustriesResolverObject : public ResolverObject {
-	IndustriesScopeResolver industries_scope;
-	TownScopeResolver *town_scope;
+	IndustriesScopeResolver industries_scope; ///< Scope resolver for the industry.
+	TownScopeResolver *town_scope;            ///< Scope resolver for the associated town (if needed and available, else \c NULL).
 
 	IndustriesResolverObject(TileIndex tile, Industry *indus, IndustryType type, uint32 random_bits = 0,
 			CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_industrytiles.cpp b/src/newgrf_industrytiles.cpp
index e778a3ac7..d23a38298 100644
--- a/src/newgrf_industrytiles.cpp
+++ b/src/newgrf_industrytiles.cpp
@@ -132,6 +132,15 @@ static const GRFFile *GetIndTileGrffile(IndustryGfx gfx)
 	return (its != NULL) ? its->grf_prop.grffile : NULL;
 }
 
+/**
+ * Constructor of the industry tiles scope resolver.
+ * @param gfx Graphics of the industry.
+ * @param tile %Tile of the industry.
+ * @param indus %Industry owning the tile.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 IndustryTileResolverObject::IndustryTileResolverObject(IndustryGfx gfx, TileIndex tile, Industry *indus,
 			CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 	: ResolverObject(GetIndTileGrffile(gfx), callback, callback_param1, callback_param2),
@@ -140,6 +149,12 @@ IndustryTileResolverObject::IndustryTileResolverObject(IndustryGfx gfx, TileInde
 {
 }
 
+/**
+ * Constructor of the scope resolver for the industry tile.
+ * @param ro Surrounding resolver.
+ * @param industry %Industry owning the tile.
+ * @param tile %Tile of the industry.
+ */
 IndustryTileScopeResolver::IndustryTileScopeResolver(ResolverObject *ro, Industry *industry, TileIndex tile) : ScopeResolver(ro)
 {
 	this->industry = industry;
diff --git a/src/newgrf_industrytiles.h b/src/newgrf_industrytiles.h
index dc8fb238f..f5b88db83 100644
--- a/src/newgrf_industrytiles.h
+++ b/src/newgrf_industrytiles.h
@@ -16,9 +16,10 @@
 #include "newgrf_industries.h"
 #include "core/random_func.hpp"
 
+/** Resolver for the industry tiles scope. */
 struct IndustryTileScopeResolver : public ScopeResolver {
-	Industry *industry;
-	TileIndex tile;
+	Industry *industry; ///< Industry owning the tiles.
+	TileIndex tile;     ///< %Tile being resolved.
 
 	IndustryTileScopeResolver(ResolverObject *ro, Industry *industry, TileIndex tile);
 
@@ -28,9 +29,10 @@ struct IndustryTileScopeResolver : public ScopeResolver {
 	/* virtual */ void SetTriggers(int triggers) const;
 };
 
+/** Resolver for industry tiles. */
 struct IndustryTileResolverObject : public ResolverObject {
-	IndustryTileScopeResolver indtile_scope;
-	IndustriesScopeResolver ind_scope;
+	IndustryTileScopeResolver indtile_scope; ///< Scope resolver for the industry tile.
+	IndustriesScopeResolver ind_scope;       ///< Scope resolver for the industry owning the tile.
 
 	IndustryTileResolverObject(IndustryGfx gfx, TileIndex tile, Industry *indus,
 			CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_object.cpp b/src/newgrf_object.cpp
index 4c1c46149..1db4b02c6 100644
--- a/src/newgrf_object.cpp
+++ b/src/newgrf_object.cpp
@@ -116,6 +116,13 @@ bool NewGRFClass<Tspec, Tid, Tmax>::IsUIAvailable(uint index) const
 
 INSTANTIATE_NEWGRF_CLASS_METHODS(ObjectClass, ObjectSpec, ObjectClassID, OBJECT_CLASS_MAX)
 
+/**
+ * Constructor of an object scope resolver.
+ * @param ro Surrounding resolver.
+ * @param obj Object being resolved.
+ * @param tile %Tile of the object.
+ * @param view View of the object.
+ */
 ObjectScopeResolver::ObjectScopeResolver(ResolverObject *ro, Object *obj, TileIndex tile, uint8 view)
 		: ScopeResolver(ro)
 {
@@ -355,6 +362,15 @@ static const SpriteGroup *GetObjectSpriteGroup(const ObjectSpec *spec, const Obj
 
 }
 
+/**
+ * Constructor of the object resolver.
+ * @param obj Object being resolved.
+ * @param tile %Tile of the object.
+ * @param view View of the object.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 ObjectResolverObject::ObjectResolverObject(const ObjectSpec *spec, Object *obj, TileIndex tile, uint8 view,
 		CallbackID callback, uint32 param1, uint32 param2)
 	: ResolverObject(spec->grf_prop.grffile, callback, param1, param2), object_scope(this, obj, tile, view)
diff --git a/src/newgrf_object.h b/src/newgrf_object.h
index a1adbb662..4ccca97b8 100644
--- a/src/newgrf_object.h
+++ b/src/newgrf_object.h
@@ -92,6 +92,7 @@ struct ObjectSpec {
 	static const ObjectSpec *GetByTile(TileIndex tile);
 };
 
+/** Object scope resolver. */
 struct ObjectScopeResolver : public ScopeResolver {
 	struct Object *obj; ///< The object the callback is ran for.
 	TileIndex tile;     ///< The tile related to the object.
@@ -105,8 +106,8 @@ struct ObjectScopeResolver : public ScopeResolver {
 
 /** A resolver object to be used with feature 0F spritegroups. */
 struct ObjectResolverObject : public ResolverObject {
-	ObjectScopeResolver object_scope;
-	TownScopeResolver *town_scope;
+	ObjectScopeResolver object_scope; ///< The object scope resolver.
+	TownScopeResolver *town_scope;    ///< The town scope resolver (created on the first call).
 
 	ObjectResolverObject(const ObjectSpec *spec, Object *o, TileIndex tile, uint8 view = 0,
 			CallbackID callback = CBID_NO_CALLBACK, uint32 param1 = 0, uint32 param2 = 0);
diff --git a/src/newgrf_railtype.cpp b/src/newgrf_railtype.cpp
index 4e1673ab2..36ac7260a 100644
--- a/src/newgrf_railtype.cpp
+++ b/src/newgrf_railtype.cpp
@@ -65,12 +65,26 @@
 	return NULL;
 }
 
+/**
+ * Constructor of the railtype scope resolvers.
+ * @param ro Surrounding resolver.
+ * @param tile %Tile containing the track. For track on a bridge this is the southern bridgehead.
+ * @param context Are we resolving sprites for the upper halftile, or on a bridge?
+ */
 RailTypeScopeResolver::RailTypeScopeResolver(ResolverObject *ro, TileIndex tile, TileContext context) : ScopeResolver(ro)
 {
 	this->tile = tile;
 	this->context = context;
 }
 
+/**
+ * Resolver object for rail types.
+ * @param tile %Tile containing the track. For track on a bridge this is the southern bridgehead.
+ * @param context Are we resolving sprites for the upper halftile, or on a bridge?
+ * @param grffile The GRF to do the lookup for.
+ * @param param1 Extra parameter (first parameter of the callback, except railtypes do not have callbacks).
+ * @param param2 Extra parameter (second parameter of the callback, except railtypes do not have callbacks).
+ */
 RailTypeResolverObject::RailTypeResolverObject(TileIndex tile, TileContext context, const GRFFile *grffile, uint32 param1, uint32 param2)
 	: ResolverObject(grffile, CBID_NO_CALLBACK, param1, param2), railtype_scope(this, tile, context)
 {
diff --git a/src/newgrf_railtype.h b/src/newgrf_railtype.h
index 9224ce9e5..c1977eaf8 100644
--- a/src/newgrf_railtype.h
+++ b/src/newgrf_railtype.h
@@ -16,7 +16,7 @@
 #include "newgrf_commons.h"
 #include "newgrf_spritegroup.h"
 
-
+/** Resolver for the railtype scope. */
 struct RailTypeScopeResolver : public ScopeResolver {
 	TileIndex tile;      ///< Tracktile. For track on a bridge this is the southern bridgehead.
 	TileContext context; ///< Are we resolving sprites for the upper halftile, or on a bridge?
@@ -29,7 +29,7 @@ struct RailTypeScopeResolver : public ScopeResolver {
 
 /** Resolver object for rail types. */
 struct RailTypeResolverObject : public ResolverObject {
-	RailTypeScopeResolver railtype_scope;
+	RailTypeScopeResolver railtype_scope; ///< Resolver for the railtype scope.
 
 	RailTypeResolverObject(TileIndex tile, TileContext context, const GRFFile *grffile, uint32 param1 = 0, uint32 param2 = 0);
 
diff --git a/src/newgrf_spritegroup.cpp b/src/newgrf_spritegroup.cpp
index 517cc885d..81b66767b 100644
--- a/src/newgrf_spritegroup.cpp
+++ b/src/newgrf_spritegroup.cpp
@@ -115,7 +115,13 @@ ScopeResolver::~ScopeResolver() {}
  */
 /* virtual */ void ScopeResolver::StorePSA(uint reg, int32 value) {}
 
-
+/**
+ * Resolver constructor.
+ * @param grffile NewGRF file asscoiated with the object (or \c NULL if none).
+ * @param callback Callback code being resolved (default value is #CBID_NO_CALLBACK).
+ * @param callback_param1 First parameter (var 10) of the callback (only used when \a callback is also set).
+ * @param callback_param2 Second parameter (var 18) of the callback (only used when \a callback is also set).
+ */
 ResolverObject::ResolverObject(const GRFFile *grffile, CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 		: default_scope(this)
 {
@@ -129,16 +135,21 @@ ResolverObject::ResolverObject(const GRFFile *grffile, CallbackID callback, uint
 
 ResolverObject::~ResolverObject() {}
 
+/**
+ * Get the real sprites of the grf.
+ * @param group Group to get.
+ * @return The available sprite group.
+ */
 /* virtual */ const SpriteGroup *ResolverObject::ResolveReal(const RealSpriteGroup *group) const
 {
 	return NULL;
 }
 
 /**
- * Get a specific ScopeResolver.
+ * Get a resolver for the \a scope.
  * @param scope Scope to return.
  * @param relative Additional parameter for #VSG_SCOPE_RELATIVE.
- * @return ScopeResolver.
+ * @return The resolver for the requested scope.
  */
 /* virtual */ ScopeResolver *ResolverObject::GetScope(VarSpriteGroupScope scope, byte relative)
 {
diff --git a/src/newgrf_spritegroup.h b/src/newgrf_spritegroup.h
index ac2f939b2..9b6d1fc0e 100644
--- a/src/newgrf_spritegroup.h
+++ b/src/newgrf_spritegroup.h
@@ -303,8 +303,14 @@ struct IndustryProductionSpriteGroup : SpriteGroup {
 
 struct ResolverObject;
 
+/**
+ * Interface to query and set values specific to a single #VarSpriteGroupScope (action 2 scope).
+ *
+ * Multiple of these interfaces are combined into a #ResolverObject to allow access
+ * to different game entities from a #SpriteGroup-chain (action 1-2-3 chain).
+ */
 struct ScopeResolver {
-	ResolverObject *ro;
+	ResolverObject *ro; ///< Surrounding resolver object.
 
 	ScopeResolver(ResolverObject *ro);
 	virtual ~ScopeResolver();
@@ -317,15 +323,21 @@ struct ScopeResolver {
 	virtual void StorePSA(uint reg, int32 value);
 };
 
+/**
+ * Interface for #SpriteGroup-s to access the gamestate.
+ *
+ * Using this interface #SpriteGroup-chains (action 1-2-3 chains) can be resolved,
+ * to get the results of callbacks, rerandomisations or normal sprite lookups.
+ */
 struct ResolverObject {
 	ResolverObject(const GRFFile *grffile, CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
 	virtual ~ResolverObject();
 
 	ScopeResolver default_scope; ///< Default implementation of the grf scope.
 
-	CallbackID callback;
-	uint32 callback_param1;
-	uint32 callback_param2;
+	CallbackID callback;        ///< Callback being resolved.
+	uint32 callback_param1;     ///< First parameter (var 10) of the callback.
+	uint32 callback_param2;     ///< Second parameter (var 18) of the callback.
 
 	byte trigger;
 
diff --git a/src/newgrf_station.cpp b/src/newgrf_station.cpp
index 61f8bb5a3..4b5c5468a 100644
--- a/src/newgrf_station.cpp
+++ b/src/newgrf_station.cpp
@@ -523,6 +523,15 @@ uint32 Waypoint::GetNewGRFVariable(const ResolverObject *object, byte variable,
 	return group->loading[0];
 }
 
+/**
+ * Resolver for stations.
+ * @param statspec Station (type) specification.
+ * @param st Instance of the station.
+ * @param tile %Tile of the station.
+ * @param callback Callback ID.
+ * @param callback_param1 First parameter (var 10) of the callback.
+ * @param callback_param2 Second parameter (var 18) of the callback.
+ */
 StationResolverObject::StationResolverObject(const StationSpec *statspec, BaseStation *st, TileIndex tile,
 		CallbackID callback, uint32 callback_param1, uint32 callback_param2)
 	: ResolverObject((statspec != NULL ? statspec->grf_prop.grffile : NULL), callback, callback_param1, callback_param2),
@@ -537,6 +546,13 @@ StationResolverObject::~StationResolverObject()
 	delete this->town_scope;
 }
 
+/**
+ * Constructor for station scopes.
+ * @param ro Surrounding resolver.
+ * @param statspec Station (type) specification.
+ * @param st Instance of the station.
+ * @param tile %Tile of the station.
+ */
 StationScopeResolver::StationScopeResolver(ResolverObject *ro, const StationSpec *statspec, BaseStation *st, TileIndex tile)
 	: ScopeResolver(ro)
 {
diff --git a/src/newgrf_station.h b/src/newgrf_station.h
index ee7757376..a536687a6 100644
--- a/src/newgrf_station.h
+++ b/src/newgrf_station.h
@@ -22,12 +22,13 @@
 #include "newgrf_spritegroup.h"
 #include "newgrf_town.h"
 
+/** Scope resolver for stations. */
 struct StationScopeResolver : public ScopeResolver {
-	TileIndex tile;
-	struct BaseStation *st;
-	const struct StationSpec *statspec;
-	CargoID cargo_type;
-	Axis axis;                     ///< Station axis, used only for the slope check callback.
+	TileIndex tile;                     ///< %Tile of the station.
+	struct BaseStation *st;             ///< Instance of the station.
+	const struct StationSpec *statspec; ///< Station (type) specification.
+	CargoID cargo_type;                 ///< Type of cargo of the station.
+	Axis axis;                          ///< Station axis, used only for the slope check callback.
 
 	StationScopeResolver(ResolverObject *ro, const StationSpec *statspec, BaseStation *st, TileIndex tile);
 
@@ -38,9 +39,10 @@ struct StationScopeResolver : public ScopeResolver {
 	/* virtual */ uint32 GetVariable(byte variable, uint32 parameter, bool *available) const;
 };
 
+/** Station resolver. */
 struct StationResolverObject : public ResolverObject {
-	StationScopeResolver station_scope;
-	TownScopeResolver *town_scope;
+	StationScopeResolver station_scope; ///< The station scope resolver.
+	TownScopeResolver *town_scope;      ///< The town scope resolver (created on the first call).
 
 	StationResolverObject(const StationSpec *statspec, BaseStation *st, TileIndex tile,
 			CallbackID callback = CBID_NO_CALLBACK, uint32 callback_param1 = 0, uint32 callback_param2 = 0);
diff --git a/src/newgrf_town.cpp b/src/newgrf_town.cpp
index 64514d3e6..95cab9643 100644
--- a/src/newgrf_town.cpp
+++ b/src/newgrf_town.cpp
@@ -14,6 +14,12 @@
 #include "town.h"
 #include "newgrf_town.h"
 
+/**
+ * Resolver of a town scope.
+ * @param ro Surrounding resolver.
+ * @param t %Town of the scope.
+ * @param readonly Scope may change persistent storage of the town.
+ */
 TownScopeResolver::TownScopeResolver(ResolverObject *ro, Town *t, bool readonly) : ScopeResolver(ro)
 {
 	this->t = t;
@@ -154,6 +160,12 @@ TownScopeResolver::TownScopeResolver(ResolverObject *ro, Town *t, bool readonly)
 	t->psa_list.push_back(psa);
 }
 
+/**
+ * Resolver for a town.
+ * @param grffile NewGRF file associated with the town.
+ * @param t %Town of the scope.
+ * @param readonly Scope may change persistent storage of the town.
+ */
 TownResolverObject::TownResolverObject(const struct GRFFile *grffile, Town *t, bool readonly)
 		: ResolverObject(grffile), town_scope(this, t, readonly)
 {
diff --git a/src/newgrf_town.h b/src/newgrf_town.h
index cd090a7ac..3f6094cdb 100644
--- a/src/newgrf_town.h
+++ b/src/newgrf_town.h
@@ -15,13 +15,15 @@
 #include "town_type.h"
 #include "newgrf_spritegroup.h"
 
-/* Currently there is no direct town resolver; we only need to get town
- * variable results from inside stations, house tiles and industries,
- * and to check the town's persistent storage.
+/**
+ * Scope resolver for a town.
+ * @note Currently there is no direct town resolver; we only need to get town
+ *       variable results from inside stations, house tiles and industries,
+ *       and to check the town's persistent storage.
  */
 struct TownScopeResolver : public ScopeResolver {
-	Town *t;
-	bool readonly;
+	Town *t;       ///< %Town of the scope.
+	bool readonly; ///< When set, persistent storage of the town is read-only,
 
 	TownScopeResolver(ResolverObject *ro, Town *t, bool readonly);
 
@@ -29,8 +31,9 @@ struct TownScopeResolver : public ScopeResolver {
 	virtual void StorePSA(uint reg, int32 value);
 };
 
+/** Resolver of town properties. */
 struct TownResolverObject : public ResolverObject {
-	TownScopeResolver town_scope;
+	TownScopeResolver town_scope; ///< Scope resolver specific for towns.
 
 	TownResolverObject(const struct GRFFile *grffile, Town *t, bool readonly);