(svn r5018) [YAPF] Added some comments to YAPF implementation.

9 files changed, 172 insertions, 75 deletions

diff --git a/yapf/unittest/test_yapf.h b/yapf/unittest/test_yapf.h
index ca4b21de0..558ea4667 100644
--- a/yapf/unittest/test_yapf.h
+++ b/yapf/unittest/test_yapf.h
@@ -132,9 +132,9 @@ typedef CTestYapfNodeT<CNodeKey2> CYapfNode2;
 template <class Types>
 struct CYapfTestBaseT
 {
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 	typedef typename Types::Map Map;
 
 	int m_x1, m_y1;
@@ -155,9 +155,13 @@ struct CYapfTestBaseT
 		m_td1 = td1;
 	}
 
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 	FORCEINLINE char TransportTypeChar() const {return 'T';}
 
+	/** Called by YAPF to move from the given node to the next tile. For each
+	*   reachable trackdir on the new tile creates new node, initializes it
+	*   and adds it to the open list by calling Yapf().AddNewNode(n) */
 	FORCEINLINE void PfFollowNode(Node& org)
 	{
 		int x_org = org.m_key.m_x;
@@ -191,6 +195,7 @@ struct CYapfTestBaseT
 		}
 	}
 
+	/// Called when YAPF needs to place origin nodes into open list
 	FORCEINLINE void PfSetStartupNodes()
 	{
 		Node& n1 = Yapf().CreateNewNode();
@@ -201,6 +206,9 @@ struct CYapfTestBaseT
 		Yapf().AddStartupNode(n1);
 	}
 
+	/** Called by YAPF to calculate the cost from the origin to the given node.
+	*   Calculates only the cost of given node, adds it to the parent node cost
+	*   and stores the result into Node::m_cost member */
 	FORCEINLINE bool PfCalcCost(Node& n)
 	{
 		// base tile cost depending on distance
@@ -216,6 +224,8 @@ struct CYapfTestBaseT
 		return true;
 	}
 
+	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	*   adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
 	FORCEINLINE bool PfCalcEstimate(Node& n)
 	{
 		int dx = abs(n.m_key.m_x - m_x2);
@@ -227,6 +237,7 @@ struct CYapfTestBaseT
 		return true;
 	}
 
+	/// Called by YAPF to detect if node ends in the desired destination
 	FORCEINLINE bool PfDetectDestination(Node& n)
 	{
 		bool bDest = (n.m_key.m_x == m_x2) && (n.m_key.m_y == m_y2);
diff --git a/yapf/yapf_base.hpp b/yapf/yapf_base.hpp
index c504fc468..04eefb885 100644
--- a/yapf/yapf_base.hpp
+++ b/yapf/yapf_base.hpp
@@ -45,34 +45,34 @@ extern int _total_pf_time_us;
 template <class Types>
 class CYapfBaseT {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;           ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList NodeList; ///< our node list
 	typedef typename NodeList::Titem Node;     ///< this will be our node type
 	typedef typename Node::Key Key;            ///< key to hash tables
 
 
-	NodeList             m_nodes;         ///< node list multi-container
+	NodeList             m_nodes;              ///< node list multi-container
 protected:
-	Node*                m_pBestDestNode; ///< pointer to the destination node found at last round
-	Node*                m_pBestIntermediateNode;
-	const YapfSettings  *m_settings;
-	int                  m_max_search_nodes;
-	Vehicle*             m_veh;
+	Node*                m_pBestDestNode;      ///< pointer to the destination node found at last round
+	Node*                m_pBestIntermediateNode; ///< here should be node closest to the destination if path not found
+	const YapfSettings  *m_settings;           ///< current settings (_patches.yapf)
+	int                  m_max_search_nodes;   ///< maximum number of nodes we are allowed to visit before we give up
+	Vehicle*             m_veh;                ///< vehicle that we are trying to drive
 
-	int                  m_stats_cost_calcs;
-	int                  m_stats_cache_hits;
+	int                  m_stats_cost_calcs;   ///< stats - how many node's costs were calculated
+	int                  m_stats_cache_hits;   ///< stats - how many node's costs were reused from cache
 
 public:
-	CPerformanceTimer    m_perf_cost;
-	CPerformanceTimer    m_perf_slope_cost;
-	CPerformanceTimer    m_perf_ts_cost;
-	CPerformanceTimer    m_perf_other_cost;
+	CPerformanceTimer    m_perf_cost;          ///< stats - total CPU time of this run
+	CPerformanceTimer    m_perf_slope_cost;    ///< stats - slope calculation CPU time
+	CPerformanceTimer    m_perf_ts_cost;       ///< stats - GetTrackStatus() CPU time
+	CPerformanceTimer    m_perf_other_cost;    ///< stats - other CPU time
 
 public:
-	int                  m_num_steps;     ///< this is there for debugging purposes (hope it doesn't hurt)
+	int                  m_num_steps;          ///< this is there for debugging purposes (hope it doesn't hurt)
 
 public:
-	// default constructor
+	/// default constructor
 	FORCEINLINE CYapfBaseT()
 		: m_pBestDestNode(NULL)
 		, m_pBestIntermediateNode(NULL)
@@ -90,12 +90,15 @@ public:
 	{
 	}
 
+	/// default destructor
 	~CYapfBaseT() {}
 
 protected:
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/// return current settings (can be custom - player based - but later)
 	FORCEINLINE const YapfSettings& PfGetSettings() const
 	{
 		return *m_settings;
diff --git a/yapf/yapf_common.hpp b/yapf/yapf_common.hpp
index e4d937a57..127c73210 100644
--- a/yapf/yapf_common.hpp
+++ b/yapf/yapf_common.hpp
@@ -3,28 +3,31 @@
 #ifndef  YAPF_COMMON_HPP
 #define  YAPF_COMMON_HPP
 
-
+/** YAPF origin provider base class - used when origin is one tile / multiple trackdirs */
 template <class Types>
 class CYapfOriginTileT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 
 protected:
-	TileIndex    m_orgTile;
-	TrackdirBits m_orgTrackdirs;
+	TileIndex    m_orgTile;                       ///< origin tile
+	TrackdirBits m_orgTrackdirs;                  ///< origin trackdir mask
 
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/// Set origin tile / trackdir mask
 	void SetOrigin(TileIndex tile, TrackdirBits trackdirs)
 	{
 		m_orgTile = tile;
 		m_orgTrackdirs = trackdirs;
 	}
 
+	/// Called when YAPF needs to place origin nodes into open list
 	void PfSetStartupNodes()
 	{
 		for (TrackdirBits tdb = m_orgTrackdirs; tdb != TRACKDIR_BIT_NONE; tdb = (TrackdirBits)KillFirstBit2x64(tdb)) {
@@ -36,25 +39,28 @@ public:
 	}
 };
 
+/** YAPF origin provider base class - used when there are two tile/trackdir origins */
 template <class Types>
 class CYapfOriginTileTwoWayT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 
 protected:
-	TileIndex   m_orgTile;
-	Trackdir    m_orgTd;
-	TileIndex   m_revTile;
-	Trackdir    m_revTd;
-	int         m_reverse_penalty;
-	bool        m_treat_first_red_two_way_signal_as_eol;
-
+	TileIndex   m_orgTile;                        ///< first origin tile
+	Trackdir    m_orgTd;                          ///< first origin trackdir
+	TileIndex   m_revTile;                        ///< second (reversed) origin tile
+	Trackdir    m_revTd;                          ///< second (reversed) origin trackdir
+	int         m_reverse_penalty;                ///< penalty to be added for using the reversed origin
+	bool        m_treat_first_red_two_way_signal_as_eol; ///< in some cases (leaving station) we need to handle first two-way signal differently
+
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/// set origin (tiles, trackdirs, etc.)
 	void SetOrigin(TileIndex tile, Trackdir td, TileIndex tiler = INVALID_TILE, Trackdir tdr = INVALID_TRACKDIR, int reverse_penalty = 0, bool treat_first_red_two_way_signal_as_eol = true)
 	{
 		m_orgTile = tile;
@@ -65,6 +71,7 @@ public:
 		m_treat_first_red_two_way_signal_as_eol = treat_first_red_two_way_signal_as_eol;
 	}
 
+	/// Called when YAPF needs to place origin nodes into open list
 	void PfSetStartupNodes()
 	{
 		if (m_orgTile != INVALID_TILE && m_orgTd != INVALID_TRACKDIR) {
@@ -80,25 +87,28 @@ public:
 		}
 	}
 
+	/// return true if first two-way signal should be treated as dead end
 	FORCEINLINE bool TreatFirstRedTwoWaySignalAsEOL()
 	{
 		return Yapf().PfGetSettings().rail_firstred_twoway_eol && m_treat_first_red_two_way_signal_as_eol;
 	}
 };
 
+/** YAPF destination provider base class - used when destination is single tile / multiple trackdirs */
 template <class Types>
 class CYapfDestinationTileT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 
 protected:
-	TileIndex    m_destTile;
-	TrackdirBits m_destTrackdirs;
+	TileIndex    m_destTile;                      ///< destination tile
+	TrackdirBits m_destTrackdirs;                 ///< destination trackdir mask
 
 public:
+	/// set the destination tile / more trackdirs
 	void SetDestination(TileIndex tile, TrackdirBits trackdirs)
 	{
 		m_destTile = tile;
@@ -106,15 +116,19 @@ public:
 	}
 
 protected:
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/// Called by YAPF to detect if node ends in the desired destination
 	FORCEINLINE bool PfDetectDestination(Node& n)
 	{
 		bool bDest = (n.m_key.m_tile == m_destTile) && ((m_destTrackdirs & TrackdirToTrackdirBits(n.GetTrackdir())) != TRACKDIR_BIT_NONE);
 		return bDest;
 	}
 
+	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	*   adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
 	inline bool PfCalcEstimate(Node& n)
 	{
 		int dx = abs(TileX(n.GetTile()) - TileX(m_destTile));
@@ -128,14 +142,18 @@ public:
 	}
 };
 
+/** YAPF template that uses Ttypes template argument to determine all YAPF
+*   components (base classes) from which the actual YAPF is composed.
+*   For example classes consult: CYapfRail_TypesT template and its instantiations:
+*   CYapfRail1, CYapfRail2, CYapfRail3, CYapfAnyDepotRail1, CYapfAnyDepotRail2, CYapfAnyDepotRail3 */
 template <class Ttypes>
 class CYapfT
-	: public Ttypes::PfBase
-	, public Ttypes::PfCost
-	, public Ttypes::PfCache
-	, public Ttypes::PfOrigin
-	, public Ttypes::PfDestination
-	, public Ttypes::PfFollow
+	: public Ttypes::PfBase         ///< Instance of CYapfBaseT - main YAPF loop and support base class
+	, public Ttypes::PfCost         ///< Cost calculation provider base class
+	, public Ttypes::PfCache        ///< Segment cost cache provider
+	, public Ttypes::PfOrigin       ///< Origin (tile or two-tile origin)
+	, public Ttypes::PfDestination  ///< Destination detector and distance (estimate) calculation provider
+	, public Ttypes::PfFollow       ///< Node follower (stepping provider)
 {
 };
 
diff --git a/yapf/yapf_costcache.hpp b/yapf/yapf_costcache.hpp
index 4947e6cef..ee4029e0c 100644
--- a/yapf/yapf_costcache.hpp
+++ b/yapf/yapf_costcache.hpp
@@ -11,14 +11,18 @@ template <class Types>
 class CYapfSegmentCostCacheNoneT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
 
+	/** Called by YAPF to attach cached or local segment cost data to the given node.
+	*   @return true if globally cached data were used or false if local data was used */
 	FORCEINLINE bool PfNodeCacheFetch(Node& n)
 	{
 		return false;
 	};
 
+	/** Called by YAPF to flush the cached segment cost data back into cache storage.
+	*   Current cache implementation doesn't use that. */
 	FORCEINLINE void PfNodeCacheFlush(Node& n)
 	{
 	};
@@ -33,9 +37,9 @@ template <class Types>
 class CYapfSegmentCostCacheLocalT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 	typedef typename Node::CachedData CachedData;
 	typedef typename CachedData::Key CacheKey;
 	typedef CArrayT<CachedData> LocalCache;
@@ -43,9 +47,12 @@ public:
 protected:
 	LocalCache      m_local_cache;
 
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/** Called by YAPF to attach cached or local segment cost data to the given node.
+	*   @return true if globally cached data were used or false if local data was used */
 	FORCEINLINE bool PfNodeCacheFetch(Node& n)
 	{
 		CacheKey key(n.GetKey());
@@ -53,13 +60,19 @@ public:
 		return false;
 	};
 
+	/** Called by YAPF to flush the cached segment cost data back into cache storage.
+	*   Current cache implementation doesn't use that. */
 	FORCEINLINE void PfNodeCacheFlush(Node& n)
 	{
 	};
 };
 
 
-
+/** Base class for segment cost cache providers. Contains global counter
+*   of track layout changes and static notification function called whenever
+*   the track layout changes. It is implemented as base class because it needs
+*   to be shared between all rail YAPF types (one shared counter, one notification
+*   function. */
 struct CSegmentCostCacheBase
 {
 	static int   s_rail_change_counter;
@@ -76,7 +89,6 @@ struct CSegmentCostCacheBase
     of the segment (origin tile and exit-dir from this tile).
     Different CYapfCachedCostT types can share the same type of CSegmentCostCacheT.
     Look at CYapfRailSegment (yapf_node_rail.hpp) for the segment example */
-
 template <class Tsegment>
 struct CSegmentCostCacheT
 	: public CSegmentCostCacheBase
@@ -116,7 +128,7 @@ class CYapfSegmentCostCacheGlobalT
 {
 public:
 	typedef CYapfSegmentCostCacheLocalT<Types> Tlocal;
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
 	typedef typename Node::Key Key;    ///< key to hash tables
 	typedef typename Node::CachedData CachedData;
@@ -128,6 +140,7 @@ protected:
 
 	FORCEINLINE CYapfSegmentCostCacheGlobalT() : m_global_cache(stGetGlobalCache()) {};
 
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 	FORCEINLINE static Cache*& stGlobalCachePtr() {static Cache* pC = NULL; return pC;}
@@ -159,6 +172,8 @@ protected:
 	}
 
 public:
+	/** Called by YAPF to attach cached or local segment cost data to the given node.
+	*   @return true if globally cached data were used or false if local data was used */
 	FORCEINLINE bool PfNodeCacheFetch(Node& n)
 	{
 		if (!Yapf().CanUseGlobalCache(n)) {
@@ -171,6 +186,8 @@ public:
 		return found;
 	};
 
+	/** Called by YAPF to flush the cached segment cost data back into cache storage.
+	*   Current cache implementation doesn't use that. */
 	FORCEINLINE void PfNodeCacheFlush(Node& n)
 	{
 	};
diff --git a/yapf/yapf_costrail.hpp b/yapf/yapf_costrail.hpp
index 3c01e47d0..d8ebe3f5e 100644
--- a/yapf/yapf_costrail.hpp
+++ b/yapf/yapf_costrail.hpp
@@ -10,10 +10,10 @@ class CYapfCostRailT
 	, public CostRailSettings
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 	typedef typename Node::CachedData CachedData;
 
 protected:
@@ -33,6 +33,7 @@ protected:
 			pen[i] = p0 + i * (p1 + i * p2);
 	}
 
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
@@ -140,6 +141,9 @@ public:
 public:
 	FORCEINLINE void SetMaxCost(int max_cost) {m_max_cost = max_cost;}
 
+	/** Called by YAPF to calculate the cost from the origin to the given node.
+	*   Calculates only the cost of given node, adds it to the parent node cost
+	*   and stores the result into Node::m_cost member */
 	FORCEINLINE bool PfCalcCost(Node& n)
 	{
 		assert(!n.flags_u.flags_s.m_targed_seen);
diff --git a/yapf/yapf_destrail.hpp b/yapf/yapf_destrail.hpp
index a0e3e922d..c7b3a63a0 100644
--- a/yapf/yapf_destrail.hpp
+++ b/yapf/yapf_destrail.hpp
@@ -25,18 +25,22 @@ class CYapfDestinationAnyDepotRailT
 	: public CYapfDestinationRailBase
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
+	/// Called by YAPF to detect if node ends in the desired destination
 	FORCEINLINE bool PfDetectDestination(Node& n)
 	{
 		bool bDest = IsTileDepotType(n.GetLastTile(), TRANSPORT_RAIL);
 		return bDest;
 	}
 
+	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	*   adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
 	FORCEINLINE bool PfCalcEstimate(Node& n)
 	{
 		n.m_estimate = n.m_cost;
@@ -49,15 +53,16 @@ class CYapfDestinationTileOrStationRailT
 	: public CYapfDestinationRailBase
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 
 protected:
 	TileIndex    m_destTile;
 	TrackdirBits m_destTrackdirs;
 	StationID    m_dest_station_id;
 
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 	static TileIndex CalcStationCenterTile(StationID station)
@@ -85,6 +90,7 @@ public:
 		CYapfDestinationRailBase::SetDestination(v);
 	}
 
+	/// Called by YAPF to detect if node ends in the desired destination
 	FORCEINLINE bool PfDetectDestination(Node& n)
 	{
 		bool bDest;
@@ -99,6 +105,8 @@ public:
 		return bDest;
 	}
 
+	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	*   adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
 	FORCEINLINE bool PfCalcEstimate(Node& n)
 	{
 		static int dg_dir_to_x_offs[] = {-1, 0, 1, 0};
diff --git a/yapf/yapf_rail.cpp b/yapf/yapf_rail.cpp
index 67d3d781f..7f0b11e27 100644
--- a/yapf/yapf_rail.cpp
+++ b/yapf/yapf_rail.cpp
@@ -17,15 +17,19 @@ template <class Types>
 class CYapfFollowAnyDepotRailT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;                     ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
-	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Types::NodeList::Titem Node;        ///< this will be our node type
+	typedef typename Node::Key Key;                      ///< key to hash tables
 
 protected:
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/** Called by YAPF to move from the given node to the next tile. For each
+	*   reachable trackdir on the new tile creates new node, initializes it
+	*   and adds it to the open list by calling Yapf().AddNewNode(n) */
 	inline void PfFollowNode(Node& old_node)
 	{
 		TrackFollower F(Yapf().GetVehicle());
@@ -33,6 +37,7 @@ public:
 			Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
 	}
 
+	/// return debug report character to identify the transportation type
 	FORCEINLINE char TransportTypeChar() const {return 't';}
 
 	static bool stFindNearestDepotTwoWay(Vehicle *v, TileIndex t1, Trackdir td1, TileIndex t2, Trackdir td2, int max_distance, int reverse_penalty, TileIndex* depot_tile, bool* reversed)
@@ -75,15 +80,19 @@ template <class Types>
 class CYapfFollowRailT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;                     ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
-	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Types::NodeList::Titem Node;        ///< this will be our node type
+	typedef typename Node::Key Key;                      ///< key to hash tables
 
 protected:
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/** Called by YAPF to move from the given node to the next tile. For each
+	*   reachable trackdir on the new tile creates new node, initializes it
+	*   and adds it to the open list by calling Yapf().AddNewNode(n) */
 	inline void PfFollowNode(Node& old_node)
 	{
 		TrackFollower F(Yapf().GetVehicle());
@@ -91,6 +100,7 @@ public:
 			Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
 	}
 
+	/// return debug report character to identify the transportation type
 	FORCEINLINE char TransportTypeChar() const {return 't';}
 
 	static Trackdir stChooseRailTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir, TrackdirBits trackdirs)
diff --git a/yapf/yapf_road.cpp b/yapf/yapf_road.cpp
index dd3529aff..7dee8ab3a 100644
--- a/yapf/yapf_road.cpp
+++ b/yapf/yapf_road.cpp
@@ -10,12 +10,13 @@ template <class Types>
 class CYapfCostRoadT
 {
 public:
-	typedef typename Types::Tpf Tpf;
-	typedef typename Types::TrackFollower TrackFollower;
+	typedef typename Types::Tpf Tpf; ///< pathfinder (derived from THIS class)
+	typedef typename Types::TrackFollower TrackFollower; ///< track follower helper
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
 	typedef typename Node::Key Key;    ///< key to hash tables
 
 protected:
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 	int SlopeCost(TileIndex tile, TileIndex next_tile, Trackdir trackdir)
@@ -62,6 +63,9 @@ protected:
 	}
 
 public:
+	/** Called by YAPF to calculate the cost from the origin to the given node.
+	*   Calculates only the cost of given node, adds it to the parent node cost
+	*   and stores the result into Node::m_cost member */
 	FORCEINLINE bool PfCalcCost(Node& n)
 	{
 		int segment_cost = 0;
@@ -118,19 +122,23 @@ template <class Types>
 class CYapfDestinationAnyDepotRoadT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;                     ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
-	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Types::NodeList::Titem Node;        ///< this will be our node type
+	typedef typename Node::Key Key;                      ///< key to hash tables
 
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
+	/// Called by YAPF to detect if node ends in the desired destination
 	FORCEINLINE bool PfDetectDestination(Node& n)
 	{
 		bool bDest = IsTileDepotType(n.m_segment_last_tile, TRANSPORT_ROAD);
 		return bDest;
 	}
 
+	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	*   adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
 	FORCEINLINE bool PfCalcEstimate(Node& n)
 	{
 		n.m_estimate = n.m_cost;
@@ -143,10 +151,10 @@ template <class Types>
 class CYapfDestinationTileRoadT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;                     ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
-	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Types::NodeList::Titem Node;        ///< this will be our node type
+	typedef typename Node::Key Key;                      ///< key to hash tables
 
 protected:
 	TileIndex    m_destTile;
@@ -160,15 +168,19 @@ public:
 	}
 
 protected:
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/// Called by YAPF to detect if node ends in the desired destination
 	FORCEINLINE bool PfDetectDestination(Node& n)
 	{
 		bool bDest = (n.m_segment_last_tile == m_destTile) && ((m_destTrackdirs & TrackdirToTrackdirBits(n.m_segment_last_td)) != TRACKDIR_BIT_NONE);
 		return bDest;
 	}
 
+	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	*   adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
 	inline bool PfCalcEstimate(Node& n)
 	{
 		static int dg_dir_to_x_offs[] = {-1, 0, 1, 0};
@@ -201,16 +213,20 @@ template <class Types>
 class CYapfFollowRoadT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;                     ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
-	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Types::NodeList::Titem Node;        ///< this will be our node type
+	typedef typename Node::Key Key;                      ///< key to hash tables
 
 protected:
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
 
+	/** Called by YAPF to move from the given node to the next tile. For each
+	*   reachable trackdir on the new tile creates new node, initializes it
+	*   and adds it to the open list by calling Yapf().AddNewNode(n) */
 	inline void PfFollowNode(Node& old_node)
 	{
 		TrackFollower F;
@@ -218,6 +234,7 @@ public:
 			Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
 	}
 
+	/// return debug report character to identify the transportation type
 	FORCEINLINE char TransportTypeChar() const {return 'r';}
 
 	static Trackdir stChooseRoadTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir)
diff --git a/yapf/yapf_ship.cpp b/yapf/yapf_ship.cpp
index c19f6bbdd..86d20c9f1 100644
--- a/yapf/yapf_ship.cpp
+++ b/yapf/yapf_ship.cpp
@@ -9,15 +9,19 @@ template <class Types>
 class CYapfFollowShipT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;                     ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::TrackFollower TrackFollower;
-	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Types::NodeList::Titem Node;        ///< this will be our node type
+	typedef typename Node::Key Key;                      ///< key to hash tables
 
 protected:
+	/// to access inherited path finder
 	FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/** Called by YAPF to move from the given node to the next tile. For each
+	*   reachable trackdir on the new tile creates new node, initializes it
+	*   and adds it to the open list by calling Yapf().AddNewNode(n) */
 	inline void PfFollowNode(Node& old_node)
 	{
 		TrackFollower F;
@@ -25,6 +29,7 @@ public:
 			Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
 	}
 
+	/// return debug report character to identify the transportation type
 	FORCEINLINE char TransportTypeChar() const {return 'w';}
 
 	static Trackdir ChooseShipTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks)
@@ -80,14 +85,18 @@ template <class Types>
 class CYapfCostShipT
 {
 public:
-	typedef typename Types::Tpf Tpf;
+	typedef typename Types::Tpf Tpf;              ///< the pathfinder class (derived from THIS class)
 	typedef typename Types::NodeList::Titem Node; ///< this will be our node type
-	typedef typename Node::Key Key;    ///< key to hash tables
+	typedef typename Node::Key Key;               ///< key to hash tables
 
 protected:
+	/// to access inherited path finder
 	Tpf& Yapf() {return *static_cast<Tpf*>(this);}
 
 public:
+	/** Called by YAPF to calculate the cost from the origin to the given node.
+	*   Calculates only the cost of given node, adds it to the parent node cost
+	*   and stores the result into Node::m_cost member */
 	FORCEINLINE bool PfCalcCost(Node& n)
 	{
 		// base tile cost depending on distance