(svn r20283) -Codechange: Unify start of doygen comments.

14 files changed, 86 insertions, 43 deletions

diff --git a/src/pathfinder/follow_track.hpp b/src/pathfinder/follow_track.hpp
index 70660d653..424bdec17 100644
--- a/src/pathfinder/follow_track.hpp
+++ b/src/pathfinder/follow_track.hpp
@@ -21,7 +21,8 @@
 #include "../depot_map.h"
 #include "pf_performance_timer.hpp"
 
-/** Track follower helper template class (can serve pathfinders and vehicle
+/**
+ * Track follower helper template class (can serve pathfinders and vehicle
  *  controllers). See 6 different typedefs below for 3 different transport
  *  types w/ or w/o 90-deg turns allowed */
 template <TransportType Ttr_type_, typename VehicleType, bool T90deg_turns_allowed_ = true, bool Tmask_reserved_tracks = false>
@@ -110,7 +111,8 @@ struct CFollowTrackT
 		return INVALID_DIAGDIR;
 	}
 
-	/** main follower routine. Fills all members and return true on success.
+	/**
+	 * main follower routine. Fills all members and return true on success.
 	 *  Otherwise returns false if track can't be followed. */
 	inline bool Follow(TileIndex old_tile, Trackdir old_td)
 	{
diff --git a/src/pathfinder/npf/aystar.h b/src/pathfinder/npf/aystar.h
index 5be2dd3e4..864cdd486 100644
--- a/src/pathfinder/npf/aystar.h
+++ b/src/pathfinder/npf/aystar.h
@@ -7,7 +7,8 @@
  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** @file aystar.h
+/**
+ * @file aystar.h
  * This file has the header for AyStar
  *  AyStar is a fast pathfinding routine and is used for things like
  *  AI_pathfinding and Train_pathfinding.
diff --git a/src/pathfinder/npf/queue.cpp b/src/pathfinder/npf/queue.cpp
index d4850a0fc..791cbfe38 100644
--- a/src/pathfinder/npf/queue.cpp
+++ b/src/pathfinder/npf/queue.cpp
@@ -435,7 +435,8 @@ void clear_Hash(Hash *h, bool free_values)
 	h->size = 0;
 }
 
-/** Finds the node that that saves this key pair. If it is not
+/**
+ * Finds the node that that saves this key pair. If it is not
  * found, returns NULL. If it is found, *prev is set to the
  * node before the one found, or if the node found was the first in the bucket
  * to NULL. If it is not found, *prev is set to the last HashNode in the
diff --git a/src/pathfinder/npf/queue.h b/src/pathfinder/npf/queue.h
index 1d94ac740..3f042b7ad 100644
--- a/src/pathfinder/npf/queue.h
+++ b/src/pathfinder/npf/queue.h
@@ -98,7 +98,8 @@ void init_InsSort(Queue *q);
 /* The amount of elements that will be malloc'd at a time */
 #define BINARY_HEAP_BLOCKSIZE_BITS 10
 
-/** Initializes a binary heap and allocates internal memory for maximum of
+/**
+ * Initializes a binary heap and allocates internal memory for maximum of
  * max_size elements */
 void init_BinaryHeap(Queue *q, uint max_size);
 
@@ -133,20 +134,24 @@ struct Hash {
 
 /* Call these function to manipulate a hash */
 
-/** Deletes the value with the specified key pair from the hash and returns
+/**
+ * Deletes the value with the specified key pair from the hash and returns
  * that value. Returns NULL when the value was not present. The value returned
  * is _not_ free()'d! */
 void *Hash_Delete(Hash *h, uint key1, uint key2);
-/** Sets the value associated with the given key pair to the given value.
+/**
+ * Sets the value associated with the given key pair to the given value.
  * Returns the old value if the value was replaced, NULL when it was not yet present. */
 void *Hash_Set(Hash *h, uint key1, uint key2, void *value);
-/** Gets the value associated with the given key pair, or NULL when it is not
+/**
+ * Gets the value associated with the given key pair, or NULL when it is not
  * present. */
 void *Hash_Get(const Hash *h, uint key1, uint key2);
 
 /* Call these function to create/destroy a hash */
 
-/** Builds a new hash in an existing struct. Make sure that hash() always
+/**
+ * Builds a new hash in an existing struct. Make sure that hash() always
  * returns a hash less than num_buckets! Call delete_hash after use */
 void init_Hash(Hash *h, Hash_HashProc *hash, uint num_buckets);
 /**
diff --git a/src/pathfinder/opf/opf_ship.cpp b/src/pathfinder/opf/opf_ship.cpp
index 47c2ebc92..15c8a9ba7 100644
--- a/src/pathfinder/opf/opf_ship.cpp
+++ b/src/pathfinder/opf/opf_ship.cpp
@@ -178,7 +178,8 @@ bad:;
 	return best_bird_dist;
 }
 
-/** returns the track to choose on the next tile, or -1 when it's better to
+/**
+ * returns the track to choose on the next tile, or -1 when it's better to
  * reverse. The tile given is the tile we are about to enter, enterdir is the
  * direction in which we are entering the tile */
 Track OPFShipChooseTrack(const Ship *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks)
diff --git a/src/pathfinder/yapf/nodelist.hpp b/src/pathfinder/yapf/nodelist.hpp
index 87b262897..bc24e2893 100644
--- a/src/pathfinder/yapf/nodelist.hpp
+++ b/src/pathfinder/yapf/nodelist.hpp
@@ -16,7 +16,8 @@
 #include "../../misc/hashtable.hpp"
 #include "../../misc/binaryheap.hpp"
 
-/** Hash table based node list multi-container class.
+/**
+ * Hash table based node list multi-container class.
  *  Implements open list, closed list and priority queue for A-star
  *  path finder. */
 template <class Titem_, int Thash_bits_open_, int Thash_bits_closed_>
diff --git a/src/pathfinder/yapf/yapf_base.hpp b/src/pathfinder/yapf/yapf_base.hpp
index cbebb31ec..f98a5163a 100644
--- a/src/pathfinder/yapf/yapf_base.hpp
+++ b/src/pathfinder/yapf/yapf_base.hpp
@@ -17,7 +17,8 @@
 
 extern int _total_pf_time_us;
 
-/** CYapfBaseT - A-star type path finder base class.
+/**
+ * CYapfBaseT - A-star type path finder base class.
  *  Derive your own pathfinder from it. You must provide the following template argument:
  *    Types      - used as collection of local types used in pathfinder
  *
@@ -108,7 +109,8 @@ public:
 		return *m_settings;
 	}
 
-	/** Main pathfinder routine:
+	/**
+	 * Main pathfinder routine:
 	 *   - set startup node(s)
 	 *   - main loop that stops if:
 	 *      - the destination was found
@@ -174,7 +176,8 @@ public:
 		return bDestFound;
 	}
 
-	/** If path was found return the best node that has reached the destination. Otherwise
+	/**
+	 * If path was found return the best node that has reached the destination. Otherwise
 	 *  return the best visited node (which was nearest to the destination).
 	 */
 	FORCEINLINE Node *GetBestNode()
@@ -182,7 +185,8 @@ public:
 		return (m_pBestDestNode != NULL) ? m_pBestDestNode : m_pBestIntermediateNode;
 	}
 
-	/** Calls NodeList::CreateNewNode() - allocates new node that can be filled and used
+	/**
+	 * Calls NodeList::CreateNewNode() - allocates new node that can be filled and used
 	 *  as argument for AddStartupNode() or AddNewNode()
 	 */
 	FORCEINLINE Node& CreateNewNode()
@@ -217,7 +221,8 @@ public:
 		}
 	}
 
-	/** AddNewNode() - called by Tderived::PfFollowNode() for each child node.
+	/**
+	 * AddNewNode() - called by Tderived::PfFollowNode() for each child node.
 	 *  Nodes are evaluated here and added into open list */
 	void AddNewNode(Node &n, const TrackFollower &tf)
 	{
diff --git a/src/pathfinder/yapf/yapf_common.hpp b/src/pathfinder/yapf/yapf_common.hpp
index 51c2fc12a..cb53e2fa1 100644
--- a/src/pathfinder/yapf/yapf_common.hpp
+++ b/src/pathfinder/yapf/yapf_common.hpp
@@ -146,7 +146,8 @@ public:
 		return bDest;
 	}
 
-	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	/**
+	 * 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)
 	{
@@ -174,7 +175,8 @@ public:
 	}
 };
 
-/** YAPF template that uses Ttypes template argument to determine all YAPF
+/**
+ * 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 */
diff --git a/src/pathfinder/yapf/yapf_costcache.hpp b/src/pathfinder/yapf/yapf_costcache.hpp
index 23bdc2d7b..988a13959 100644
--- a/src/pathfinder/yapf/yapf_costcache.hpp
+++ b/src/pathfinder/yapf/yapf_costcache.hpp
@@ -14,7 +14,8 @@
 
 #include "../../date_func.h"
 
-/** CYapfSegmentCostCacheNoneT - the formal only yapf cost cache provider that implements
+/**
+ * CYapfSegmentCostCacheNoneT - the formal only yapf cost cache provider that implements
  * PfNodeCacheFetch() and PfNodeCacheFlush() callbacks. Used when nodes don't have CachedData
  * defined (they don't count with any segment cost caching).
  */
@@ -25,14 +26,16 @@ public:
 	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.
+	/**
+	 * 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.
+	/**
+	 * 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)
 	{
@@ -40,7 +43,8 @@ public:
 };
 
 
-/** CYapfSegmentCostCacheLocalT - the yapf cost cache provider that implements fake segment
+/**
+ * CYapfSegmentCostCacheLocalT - the yapf cost cache provider that implements fake segment
  * cost caching functionality for yapf. Used when node needs caching, but you don't want to
  * cache the segment costs.
  */
@@ -65,7 +69,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to attach cached or local segment cost data to the given node.
+	/**
+	 * 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)
 	{
@@ -74,7 +79,8 @@ public:
 		return false;
 	}
 
-	/** Called by YAPF to flush the cached segment cost data back into cache storage.
+	/**
+	 * 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)
 	{
@@ -82,7 +88,8 @@ public:
 };
 
 
-/** Base class for segment cost cache providers. Contains global counter
+/**
+ * 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
@@ -98,7 +105,8 @@ struct CSegmentCostCacheBase
 };
 
 
-/** CSegmentCostCacheT - template class providing hash-map and storage (heap)
+/**
+ * CSegmentCostCacheT - template class providing hash-map and storage (heap)
  *  of Tsegment structures. Each rail node contains pointer to the segment
  *  that contains cached (or non-cached) segment cost information. Nodes can
  *  differ by key type, but they use the same segment type. Segment key should
@@ -142,7 +150,8 @@ struct CSegmentCostCacheT
 	}
 };
 
-/** CYapfSegmentCostCacheGlobalT - the yapf cost cache provider that adds the segment cost
+/**
+ * CYapfSegmentCostCacheGlobalT - the yapf cost cache provider that adds the segment cost
  *  caching functionality to yapf. Using this class as base of your will provide the global
  *  segment cost caching services for your Nodes.
  */
@@ -192,7 +201,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to attach cached or local segment cost data to the given node.
+	/**
+	 * 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)
 	{
@@ -206,7 +216,8 @@ public:
 		return found;
 	}
 
-	/** Called by YAPF to flush the cached segment cost data back into cache storage.
+	/**
+	 * 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/src/pathfinder/yapf/yapf_costrail.hpp b/src/pathfinder/yapf/yapf_costrail.hpp
index e38ae52c8..088634daf 100644
--- a/src/pathfinder/yapf/yapf_costrail.hpp
+++ b/src/pathfinder/yapf/yapf_costrail.hpp
@@ -276,7 +276,8 @@ public:
 		m_max_cost = max_cost;
 	}
 
-	/** Called by YAPF to calculate the cost from the origin to the given node.
+	/**
+	 * 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, const TrackFollower *tf)
diff --git a/src/pathfinder/yapf/yapf_destrail.hpp b/src/pathfinder/yapf/yapf_destrail.hpp
index c7594df6c..0b046b207 100644
--- a/src/pathfinder/yapf/yapf_destrail.hpp
+++ b/src/pathfinder/yapf/yapf_destrail.hpp
@@ -63,7 +63,8 @@ public:
 		return bDest;
 	}
 
-	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	/**
+	 * 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)
 	{
@@ -102,7 +103,8 @@ public:
 			IsWaitingPositionFree(Yapf().GetVehicle(), tile, td, !TrackFollower::Allow90degTurns());
 	}
 
-	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	/**
+	 * 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)
 	{
@@ -181,7 +183,8 @@ public:
 		return bDest;
 	}
 
-	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	/**
+	 * 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)
 	{
diff --git a/src/pathfinder/yapf/yapf_rail.cpp b/src/pathfinder/yapf/yapf_rail.cpp
index 1fd6cfa0c..303cfd9e5 100644
--- a/src/pathfinder/yapf/yapf_rail.cpp
+++ b/src/pathfinder/yapf/yapf_rail.cpp
@@ -201,7 +201,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to move from the given node to the next tile. For each
+	/**
+	 * 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)
@@ -295,7 +296,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to move from the given node to the next tile. For each
+	/**
+	 * 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)
@@ -376,7 +378,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to move from the given node to the next tile. For each
+	/**
+	 * 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)
diff --git a/src/pathfinder/yapf/yapf_road.cpp b/src/pathfinder/yapf/yapf_road.cpp
index 47a89ab81..51162d3d2 100644
--- a/src/pathfinder/yapf/yapf_road.cpp
+++ b/src/pathfinder/yapf/yapf_road.cpp
@@ -95,7 +95,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to calculate the cost from the origin to the given node.
+	/**
+	 * 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, const TrackFollower *tf)
@@ -186,7 +187,8 @@ public:
 		return IsRoadDepotTile(tile);
 	}
 
-	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	/**
+	 * 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)
 	{
@@ -254,7 +256,8 @@ public:
 		return tile == m_destTile && ((m_destTrackdirs & TrackdirToTrackdirBits(trackdir)) != TRACKDIR_BIT_NONE);
 	}
 
-	/** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+	/**
+	 * 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)
 	{
@@ -302,7 +305,8 @@ protected:
 
 public:
 
-	/** Called by YAPF to move from the given node to the next tile. For each
+	/**
+	 * 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)
diff --git a/src/pathfinder/yapf/yapf_ship.cpp b/src/pathfinder/yapf/yapf_ship.cpp
index f30004106..f9e5c175d 100644
--- a/src/pathfinder/yapf/yapf_ship.cpp
+++ b/src/pathfinder/yapf/yapf_ship.cpp
@@ -32,7 +32,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to move from the given node to the next tile. For each
+	/**
+	 * 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)
@@ -115,7 +116,8 @@ protected:
 	}
 
 public:
-	/** Called by YAPF to calculate the cost from the origin to the given node.
+	/**
+	 * 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, const TrackFollower *tf)
@@ -136,7 +138,8 @@ public:
 	}
 };
 
-/** Config struct of YAPF for ships.
+/**
+ * Config struct of YAPF for ships.
  *  Defines all 6 base YAPF modules as classes providing services for CYapfBaseT.
  */
 template <class Tpf_, class Ttrack_follower, class Tnode_list>