(svn r21886) -Codechange: move documentation towards the code to make it more likely to be updated [n].

src/core/alloc_func.hpp

@@ -12,12 +12,13 @@
 #ifndef ALLOC_FUNC_HPP
 #define ALLOC_FUNC_HPP
 
-/**
+/*
  * Functions to exit badly with an error message.
  * It has to be linked so the error messages are not
  * duplicated in each object file making the final
  * binary needlessly large.
  */
+
 void NORETURN MallocError(size_t size);
 void NORETURN ReallocError(size_t size);
 

src/core/pool_func.hpp

@@ -20,6 +20,10 @@
 	template <class Titem, typename Tindex, size_t Tgrowth_step, size_t Tmax_size, bool Tcache, bool Tzero> \
 	type Pool<Titem, Tindex, Tgrowth_step, Tmax_size, Tcache, Tzero>
 
+/**
+ * Create a clean pool.
+ * @param name The name for the pool.
+ */
 DEFINE_POOL_METHOD(inline)::Pool(const char *name) :
 		name(name),
 		size(0),
@@ -31,6 +35,12 @@ DEFINE_POOL_METHOD(inline)::Pool(const char *name) :
 		alloc_cache(NULL)
 { }
 
+/**
+ * Resizes the pool so 'index' can be addressed
+ * @param index index we will allocate later
+ * @pre index >= this->size
+ * @pre index < Tmax_size
+ */
 DEFINE_POOL_METHOD(inline void)::ResizeFor(size_t index)
 {
 	assert(index >= this->size);
@@ -44,6 +54,10 @@ DEFINE_POOL_METHOD(inline void)::ResizeFor(size_t index)
 	this->size = new_size;
 }
 
+/**
+ * Searches for first free index
+ * @return first free index, NO_FREE_ITEM on failure
+ */
 DEFINE_POOL_METHOD(inline size_t)::FindFirstFree()
 {
 	size_t index = this->first_free;
@@ -69,6 +83,13 @@ DEFINE_POOL_METHOD(inline size_t)::FindFirstFree()
 	return NO_FREE_ITEM;
 }
 
+/**
+ * Makes given index valid
+ * @param size size of item
+ * @param index index of item
+ * @pre index < this->size
+ * @pre this->Get(index) == NULL
+ */
 DEFINE_POOL_METHOD(inline void *)::AllocateItem(size_t size, size_t index)
 {
 	assert(this->data[index] == NULL);
@@ -92,6 +113,12 @@ DEFINE_POOL_METHOD(inline void *)::AllocateItem(size_t size, size_t index)
 	return item;
 }
 
+/**
+ * Allocates new item
+ * @param size size of item
+ * @return pointer to allocated item
+ * @note error() on failure! (no free item)
+ */
 DEFINE_POOL_METHOD(void *)::GetNew(size_t size)
 {
 	size_t index = this->FindFirstFree();
@@ -104,6 +131,13 @@ DEFINE_POOL_METHOD(void *)::GetNew(size_t size)
 	return this->AllocateItem(size, index);
 }
 
+/**
+ * Allocates new item with given index
+ * @param size size of item
+ * @param index index of item
+ * @return pointer to allocated item
+ * @note usererror() on failure! (index out of range or already used)
+ */
 DEFINE_POOL_METHOD(void *)::GetNew(size_t size, size_t index)
 {
 	if (index >= Tmax_size) {
@@ -119,6 +153,12 @@ DEFINE_POOL_METHOD(void *)::GetNew(size_t size, size_t index)
 	return this->AllocateItem(size, index);
 }
 
+/**
+ * Deallocates memory used by this index and marks item as free
+ * @param index item to deallocate
+ * @pre unit is allocated (non-NULL)
+ * @note 'delete NULL' doesn't cause call of this function, so it is safe
+ */
 DEFINE_POOL_METHOD(void)::FreeItem(size_t index)
 {
 	assert(index < this->size);
@@ -136,6 +176,7 @@ DEFINE_POOL_METHOD(void)::FreeItem(size_t index)
 	if (!this->cleaning) Titem::PostDestructor(index);
 }
 
+/** Destroys all items in the pool and resets all member variables. */
 DEFINE_POOL_METHOD(void)::CleanPool()
 {
 	this->cleaning = true;

src/core/pool_type.hpp

@@ -37,9 +37,7 @@ struct Pool {
 
 	Titem **data;        ///< Pointer to array of pointers to Titem
 
-	/** Constructor */
 	Pool(const char *name);
-	/** Destroys all items in the pool and resets all member variables */
 	void CleanPool();
 
 	/**
@@ -238,52 +236,13 @@ private:
 	/** Cache of freed pointers */
 	AllocCache *alloc_cache;
 
-	/**
-	 * Makes given index valid
-	 * @param size size of item
-	 * @param index index of item
-	 * @pre index < this->size
-	 * @pre this->Get(index) == NULL
-	 */
 	void *AllocateItem(size_t size, size_t index);
-
-	/**
-	 * Resizes the pool so 'index' can be addressed
-	 * @param index index we will allocate later
-	 * @pre index >= this->size
-	 * @pre index < Tmax_size
-	 */
 	void ResizeFor(size_t index);
-
-	/**
-	 * Searches for first free index
-	 * @return first free index, NO_FREE_ITEM on failure
-	 */
 	size_t FindFirstFree();
 
-	/**
-	 * Allocates new item
-	 * @param size size of item
-	 * @return pointer to allocated item
-	 * @note error() on failure! (no free item)
-	 */
 	void *GetNew(size_t size);
-
-	/**
-	 * Allocates new item with given index
-	 * @param size size of item
-	 * @param index index of item
-	 * @return pointer to allocated item
-	 * @note usererror() on failure! (index out of range or already used)
-	 */
 	void *GetNew(size_t size, size_t index);
 
-	/**
-	 * Deallocates memory used by this index and marks item as free
-	 * @param index item to deallocate
-	 * @pre unit is allocated (non-NULL)
-	 * @note 'delete NULL' doesn't cause call of this function, so it is safe
-	 */
 	void FreeItem(size_t index);
 };
 

src/core/random_func.cpp

@@ -15,6 +15,10 @@
 
 Randomizer _random, _interactive_random;
 
+/**
+ * Generate the next pseudo random number
+ * @return the random number
+ */
 uint32 Randomizer::Next()
 {
 	const uint32 s = this->state[0];
@@ -24,17 +28,30 @@ uint32 Randomizer::Next()
 	return this->state[1] = ROR(s, 3) - 1;
 }
 
+/**
+ * Generate the next pseudo random number scaled to max
+ * @param max the maximum value of the returned random number
+ * @return the random number
+ */
 uint32 Randomizer::Next(uint32 max)
 {
 	return ((uint64)this->Next() * (uint64)max) >> 32;
 }
 
+/**
+ * (Re)set the state of the random number generator.
+ * @param seed the new state
+ */
 void Randomizer::SetSeed(uint32 seed)
 {
 	this->state[0] = seed;
 	this->state[1] = seed;
 }
 
+/**
+ * (Re)set the state of the random number generators.
+ * @param seed the new state
+ */
 void SetRandomSeed(uint32 seed)
 {
 	_random.SetSeed(seed);

src/core/random_func.hpp

@@ -37,23 +37,8 @@ struct Randomizer {
 	/** The state of the randomizer */
 	uint32 state[2];
 
-	/**
-	 * Generate the next pseudo random number
-	 * @return the random number
-	 */
 	uint32 Next();
-
-	/**
-	 * Generate the next pseudo random number scaled to max
-	 * @param max the maximum value of the returned random number
-	 * @return the random number
-	 */
 	uint32 Next(uint32 max);
-
-	/**
-	 * (Re)set the state of the random number generator.
-	 * @param seed the new state
-	 */
 	void SetSeed(uint32 seed);
 };
 extern Randomizer _random; ///< Random used in the game state calculations

src/network/core/address.cpp

@@ -16,6 +16,11 @@
 #include "address.h"
 #include "../../debug.h"
 
+/**
+ * Get the hostname; in case it wasn't given the
+ * IPv4 dotted representation is given.
+ * @return the hostname
+ */
 const char *NetworkAddress::GetHostname()
 {
 	if (StrEmpty(this->hostname) && this->address.ss_family != AF_UNSPEC) {
@@ -25,6 +30,10 @@ const char *NetworkAddress::GetHostname()
 	return this->hostname;
 }
 
+/**
+ * Get the port.
+ * @return the port.
+ */
 uint16 NetworkAddress::GetPort() const
 {
 	switch (this->address.ss_family) {
@@ -40,6 +49,10 @@ uint16 NetworkAddress::GetPort() const
 	}
 }
 
+/**
+ * Set the port.
+ * @param port set the port number.
+ */
 void NetworkAddress::SetPort(uint16 port)
 {
 	switch (this->address.ss_family) {
@@ -57,6 +70,12 @@ void NetworkAddress::SetPort(uint16 port)
 	}
 }
 
+/**
+ * Get the address as a string, e.g. 127.0.0.1:12345.
+ * @param buffer the buffer to write to
+ * @param last the last element in the buffer
+ * @param with_family whether to add the family (e.g. IPvX).
+ */
 void NetworkAddress::GetAddressAsString(char *buffer, const char *last, bool with_family)
 {
 	if (this->GetAddress()->ss_family == AF_INET6) buffer = strecpy(buffer, "[", last);
@@ -75,6 +94,12 @@ void NetworkAddress::GetAddressAsString(char *buffer, const char *last, bool wit
 	}
 }
 
+/**
+ * Get the address as a string, e.g. 127.0.0.1:12345.
+ * @param with_family whether to add the family (e.g. IPvX).
+ * @return the address
+ * @note NOT thread safe
+ */
 const char *NetworkAddress::GetAddressAsString(bool with_family)
 {
 	/* 6 = for the : and 5 for the decimal port number */
@@ -94,6 +119,10 @@ static SOCKET ResolveLoopProc(addrinfo *runp)
 	return !INVALID_SOCKET;
 }
 
+/**
+ * Get the address in its internal representation.
+ * @return the address
+ */
 const sockaddr_storage *NetworkAddress::GetAddress()
 {
 	if (!this->IsResolved()) {
@@ -107,6 +136,11 @@ const sockaddr_storage *NetworkAddress::GetAddress()
 	return &this->address;
 }
 
+/**
+ * Checks of this address is of the given family.
+ * @param family the family to check against
+ * @return true if it is of the given family
+ */
 bool NetworkAddress::IsFamily(int family)
 {
 	if (!this->IsResolved()) {
@@ -115,6 +149,12 @@ bool NetworkAddress::IsFamily(int family)
 	return this->address.ss_family == family;
 }
 
+/**
+ * Checks whether this IP address is contained by the given netmask.
+ * @param netmask the netmask in CIDR notation to test against.
+ * @note netmask without /n assumes all bits need to match.
+ * @return true if this IP is within the netmask.
+ */
 bool NetworkAddress::IsInNetmask(char *netmask)
 {
 	/* Resolve it if we didn't do it already */
@@ -169,6 +209,15 @@ bool NetworkAddress::IsInNetmask(char *netmask)
 	return true;
 }
 
+/**
+ * Resolve this address into a socket
+ * @param family the type of 'protocol' (IPv4, IPv6)
+ * @param socktype the type of socket (TCP, UDP, etc)
+ * @param flags the flags to send to getaddrinfo
+ * @param sockets the list of sockets to add the sockets to
+ * @param func the inner working while looping over the address info
+ * @return the resolved socket or INVALID_SOCKET.
+ */
 SOCKET NetworkAddress::Resolve(int family, int socktype, int flags, SocketList *sockets, LoopProc func)
 {
 	struct addrinfo *ai;
@@ -266,6 +315,10 @@ static SOCKET ConnectLoopProc(addrinfo *runp)
 	return sock;
 }
 
+/**
+ * Connect to the given address.
+ * @return the connected socket or INVALID_SOCKET.
+ */
 SOCKET NetworkAddress::Connect()
 {
 	DEBUG(net, 1, "Connecting to %s", this->GetAddressAsString());
@@ -324,6 +377,11 @@ static SOCKET ListenLoopProc(addrinfo *runp)
 	return sock;
 }
 
+/**
+ * Make the given socket listen.
+ * @param socktype the type of socket (TCP, UDP, etc)
+ * @param sockets the list of sockets to add the sockets to
+ */
 void NetworkAddress::Listen(int socktype, SocketList *sockets)
 {
 	assert(sockets != NULL);
@@ -340,6 +398,12 @@ void NetworkAddress::Listen(int socktype, SocketList *sockets)
 	}
 }
 
+/**
+ * Convert the socket type into a string
+ * @param socktype the socket type to convert
+ * @return the string representation
+ * @note only works for SOCK_STREAM and SOCK_DGRAM
+ */
 /* static */ const char *NetworkAddress::SocketTypeAsString(int socktype)
 {
 	switch (socktype) {
@@ -349,6 +413,12 @@ void NetworkAddress::Listen(int socktype, SocketList *sockets)
 	}
 }
 
+/**
+ * Convert the address family into a string
+ * @param family the family to convert
+ * @return the string representation
+ * @note only works for AF_INET, AF_INET6 and AF_UNSPEC
+ */
 /* static */ const char *NetworkAddress::AddressFamilyAsString(int family)
 {
 	switch (family) {

src/network/core/address.h

@@ -41,15 +41,6 @@ private:
 	 */
 	typedef SOCKET (*LoopProc)(addrinfo *runp);
 
-	/**
-	 * Resolve this address into a socket
-	 * @param family the type of 'protocol' (IPv4, IPv6)
-	 * @param socktype the type of socket (TCP, UDP, etc)
-	 * @param flags the flags to send to getaddrinfo
-	 * @param sockets the list of sockets to add the sockets to
-	 * @param func the inner working while looping over the address info
-	 * @return the resolved socket or INVALID_SOCKET.
-	 */
 	SOCKET Resolve(int family, int socktype, int flags, SocketList *sockets, LoopProc func);
 public:
 	/**
@@ -105,33 +96,9 @@ public:
 		memcpy(this, &address, sizeof(*this));
 	}
 
-	/**
-	 * Get the hostname; in case it wasn't given the
-	 * IPv4 dotted representation is given.
-	 * @return the hostname
-	 */
 	const char *GetHostname();
-
-	/**
-	 * Get the address as a string, e.g. 127.0.0.1:12345.
-	 * @param buffer the buffer to write to
-	 * @param last the last element in the buffer
-	 * @param with_family whether to add the family (e.g. IPvX).
-	 */
 	void GetAddressAsString(char *buffer, const char *last, bool with_family = true);
-
-	/**
-	 * Get the address as a string, e.g. 127.0.0.1:12345.
-	 * @param with_family whether to add the family (e.g. IPvX).
-	 * @return the address
-	 * @note NOT thread safe
-	 */
 	const char *GetAddressAsString(bool with_family = true);
-
-	/**
-	 * Get the address in its internal representation.
-	 * @return the address
-	 */
 	const sockaddr_storage *GetAddress();
 
 	/**
@@ -145,16 +112,7 @@ public:
 		return this->address_length;
 	}
 
-	/**
-	 * Get the port
-	 * @return the port
-	 */
 	uint16 GetPort() const;
-
-	/**
-	 * Set the port
-	 * @param port set the port number
-	 */
 	void SetPort(uint16 port);
 
 	/**
@@ -166,19 +124,7 @@ public:
 		return this->address_length != 0;
 	}
 
-	/**
-	 * Checks of this address is of the given family.
-	 * @param family the family to check against
-	 * @return true if it is of the given family
-	 */
 	bool IsFamily(int family);
-
-	/**
-	 * Checks whether this IP address is contained by the given netmask.
-	 * @param netmask the netmask in CIDR notation to test against.
-	 * @note netmask without /n assumes all bits need to match.
-	 * @return true if this IP is within the netmask.
-	 */
 	bool IsInNetmask(char *netmask);
 
 	/**
@@ -233,33 +179,10 @@ public:
 		return this->CompareTo(address) < 0;
 	}
 
-	/**
-	 * Connect to the given address.
-	 * @return the connected socket or INVALID_SOCKET.
-	 */
 	SOCKET Connect();
-
-	/**
-	 * Make the given socket listen.
-	 * @param socktype the type of socket (TCP, UDP, etc)
-	 * @param sockets the list of sockets to add the sockets to
-	 */
 	void Listen(int socktype, SocketList *sockets);
 
-	/**
-	 * Convert the socket type into a string
-	 * @param socktype the socket type to convert
-	 * @return the string representation
-	 * @note only works for SOCK_STREAM and SOCK_DGRAM
-	 */
 	static const char *SocketTypeAsString(int socktype);
-
-	/**
-	 * Convert the address family into a string
-	 * @param family the family to convert
-	 * @return the string representation
-	 * @note only works for AF_INET, AF_INET6 and AF_UNSPEC
-	 */
 	static const char *AddressFamilyAsString(int family);
 };
 

src/network/core/tcp.h

@@ -58,13 +58,8 @@ private:
 	bool killed;                ///< Whether we got killed
 	SOCKET sock;                ///< The socket we're connecting with
 
-	/** The actual connection function */
 	void Connect();
 
-	/**
-	 * Entry point for the new threads.
-	 * @param param the TCPConnecter instance to call Connect on.
-	 */
 	static void ThreadEntry(void *param);
 
 protected:
@@ -72,10 +67,6 @@ protected:
 	NetworkAddress address;
 
 public:
-	/**
-	 * Create a new connecter for the given address
-	 * @param address the (un)resolved address to connect to
-	 */
 	TCPConnecter(const NetworkAddress &address);
 	/** Silence the warnings */
 	virtual ~TCPConnecter() {}
@@ -91,15 +82,7 @@ public:
 	 */
 	virtual void OnFailure() {}
 
-	/**
-	 * Check whether we need to call the callback, i.e. whether we
-	 * have connected or aborted and call the appropriate callback
-	 * for that. It's done this way to ease on the locking that
-	 * would otherwise be needed everywhere.
-	 */
 	static void CheckCallbacks();
-
-	/** Kill all connection attempts. */
 	static void KillAll();
 };
 

src/network/core/tcp_connect.cpp

@@ -21,6 +21,10 @@
 /** List of connections that are currently being created */
 static SmallVector<TCPConnecter *,  1> _tcp_connecters;
 
+/**
+ * Create a new connecter for the given address
+ * @param address the (un)resolved address to connect to
+ */
 TCPConnecter::TCPConnecter(const NetworkAddress &address) :
 	connected(false),
 	aborted(false),
@@ -34,6 +38,7 @@ TCPConnecter::TCPConnecter(const NetworkAddress &address) :
 	}
 }
 
+/** The actual connection function */
 void TCPConnecter::Connect()
 {
 	this->sock = this->address.Connect();
@@ -44,12 +49,21 @@ void TCPConnecter::Connect()
 	}
 }
 
-
+/**
+ * Entry point for the new threads.
+ * @param param the TCPConnecter instance to call Connect on.
+ */
 /* static */ void TCPConnecter::ThreadEntry(void *param)
 {
 	static_cast<TCPConnecter*>(param)->Connect();
 }
 
+/**
+ * Check whether we need to call the callback, i.e. whether we
+ * have connected or aborted and call the appropriate callback
+ * for that. It's done this way to ease on the locking that
+ * would otherwise be needed everywhere.
+ */
 /* static */ void TCPConnecter::CheckCallbacks()
 {
 	for (TCPConnecter **iter = _tcp_connecters.Begin(); iter < _tcp_connecters.End(); /* nothing */) {
@@ -76,6 +90,7 @@ void TCPConnecter::Connect()
 	}
 }
 
+/** Kill all connection attempts. */
 /* static */ void TCPConnecter::KillAll()
 {
 	for (TCPConnecter **iter = _tcp_connecters.Begin(); iter != _tcp_connecters.End(); iter++) (*iter)->killed = true;

src/network/core/tcp_content.cpp

@@ -16,11 +16,13 @@
 #include "../../stdafx.h"
 #include "tcp_content.h"
 
+/** Clear everything in the struct */
 ContentInfo::ContentInfo()
 {
 	memset(this, 0, sizeof(*this));
 }
 
+/** Free everything allocated */
 ContentInfo::~ContentInfo()
 {
 	free(this->dependencies);
@@ -42,6 +44,10 @@ void ContentInfo::TransferFrom(ContentInfo *other)
 	}
 }
 
+/**
+ * Get the size of the data as send over the network.
+ * @return the size.
+ */
 size_t ContentInfo::Size() const
 {
 	size_t len = 0;
@@ -54,6 +60,10 @@ size_t ContentInfo::Size() const
 			sizeof(*this->dependencies) * this->dependency_count;
 }
 
+/**
+ * Is the state either selected or autoselected?
+ * @return true iff that's the case
+ */
 bool ContentInfo::IsSelected() const
 {
 	switch (this->state) {
@@ -67,6 +77,10 @@ bool ContentInfo::IsSelected() const
 	}
 }
 
+/**
+ * Is the information from this content info valid?
+ * @return true iff it's valid
+ */
 bool ContentInfo::IsValid() const
 {
 	return this->state < ContentInfo::INVALID && this->type >= CONTENT_TYPE_BEGIN && this->type < CONTENT_TYPE_END;
@@ -88,8 +102,10 @@ void NetworkContentSocketHandler::Close()
 #define CONTENT_COMMAND(type) case type: return this->NetworkPacketReceive_ ## type ## _command(p); break;
 
 /**
- * Handle an incoming packets by sending it to the correct function.
+ * Handle the given packet, i.e. pass it to the right
- * @param p the received packet
+ * parser receive command.
+ * @param p the packet to handle
+ * @return true if we should immediately handle further packets, false otherwise
  */
 bool NetworkContentSocketHandler::HandlePacket(Packet *p)
 {

src/network/core/tcp_content.h

@@ -82,30 +82,13 @@ struct ContentInfo {
 	State state;             ///< Whether the content info is selected (for download)
 	bool upgrade;            ///< This item is an upgrade
 
-	/** Clear everything in the struct */
 	ContentInfo();
-
-	/** Free everything allocated */
 	~ContentInfo();
 
 	void TransferFrom(ContentInfo *other);
 
-	/**
-	 * Get the size of the data as send over the network.
-	 * @return the size.
-	 */
 	size_t Size() const;
-
-	/**
-	 * Is the state either selected or autoselected?
-	 * @return true iff that's the case
-	 */
 	bool IsSelected() const;
-
-	/**
-	 * Is the information from this content info valid?
-	 * @return true iff it's valid
-	 */
 	bool IsValid() const;
 };
 
@@ -187,12 +170,6 @@ protected:
 	 */
 	DECLARE_CONTENT_RECEIVE_COMMAND(PACKET_CONTENT_SERVER_CONTENT);
 
-	/**
-	 * Handle the given packet, i.e. pass it to the right
-	 * parser receive command.
-	 * @param p the packet to handle
-	 * @return true if we should immediately handle further packets, false otherwise
-	 */
 	bool HandlePacket(Packet *p);
 public:
 	/**
@@ -209,7 +186,6 @@ public:
 	/** On destructing of this class, the socket needs to be closed */
 	virtual ~NetworkContentSocketHandler() { this->Close(); }
 
-	/** Do the actual receiving of packets. */
 	void ReceivePackets();
 };
 

src/network/core/tcp_http.cpp

@@ -23,6 +23,14 @@
 /** List of open HTTP connections. */
 static SmallVector<NetworkHTTPSocketHandler *, 1> _http_connections;
 
+/**
+ * Start the querying
+ * @param sock     the socket of this connection
+ * @param callback the callback for HTTP retrieval
+ * @param url      the url at the server
+ * @param data     the data to send
+ * @param depth    the depth (redirect recursion) of the queries
+ */
 NetworkHTTPSocketHandler::NetworkHTTPSocketHandler(SOCKET s,
 		HTTPCallback *callback, const char *host, const char *url,
 		const char *data, int depth) :
@@ -57,6 +65,7 @@ NetworkHTTPSocketHandler::NetworkHTTPSocketHandler(SOCKET s,
 	*_http_connections.Append() = this;
 }
 
+/** Free whatever needs to be freed. */
 NetworkHTTPSocketHandler::~NetworkHTTPSocketHandler()
 {
 	this->CloseConnection();
@@ -175,6 +184,13 @@ int NetworkHTTPSocketHandler::HandleHeader()
 	return 0;
 }
 
+/**
+ * Connect to the given URI.
+ * @param uri      the URI to connect to.
+ * @param callback the callback to send data back on.
+ * @param data     the data we want to send (as POST).
+ * @param depth    the recursion/redirect depth.
+ */
 /* static */ int NetworkHTTPSocketHandler::Connect(char *uri, HTTPCallback *callback, const char *data, int depth)
 {
 	char *hname = strstr(uri, "://");
@@ -274,6 +290,9 @@ int NetworkHTTPSocketHandler::Receive()
 	}
 }
 
+/**
+ * Do the receiving for all HTTP connections.
+ */
 /* static */ void NetworkHTTPSocketHandler::HTTPReceive()
 {
 	/* No connections, just bail out. */

src/network/core/tcp_http.h

@@ -64,33 +64,14 @@ public:
 
 	virtual NetworkRecvStatus CloseConnection(bool error = true);
 
-	/**
-	 * Start the querying
-	 * @param sock     the socket of this connection
-	 * @param callback the callback for HTTP retrieval
-	 * @param url      the url at the server
-	 * @param data     the data to send
-	 * @param depth    the depth (redirect recursion) of the queries
-	 */
 	NetworkHTTPSocketHandler(SOCKET sock, HTTPCallback *callback,
 			const char *host, const char *url, const char *data, int depth);
 
-	/** Free whatever needs to be freed. */
 	~NetworkHTTPSocketHandler();
 
-	/**
-	 * Connect to the given URI.
-	 * @param uri      the URI to connect to.
-	 * @param callback the callback to send data back on.
-	 * @param data     the data we want to send (as POST).
-	 * @param depth    the recursion/redirect depth.
-	 */
 	static int Connect(char *uri, HTTPCallback *callback,
 			const char *data = NULL, int depth = 0);
 
-	/**
-	 * Do the receiving for all HTTP connections.
-	 */
 	static void HTTPReceive();
 };
 

src/network/network_content.cpp

@@ -982,6 +982,7 @@ void ClientNetworkContentSocketHandler::CheckDependencyState(ContentInfo *ci)
 	}
 }
 
+/** Clear all downloaded content information. */
 void ClientNetworkContentSocketHandler::Clear()
 {
 	for (ContentIterator iter = this->infos.Begin(); iter != this->infos.End(); iter++) delete *iter;

src/network/network_content.h

@@ -136,7 +136,7 @@ public:
 	ConstContentIterator Get(uint32 index) const { return this->infos.Get(index); }
 	/** Get the end of the content inf iterator. */
 	ConstContentIterator End() const { return this->infos.End(); }
-	/** Clear all downloaded content information. */
+
 	void Clear();
 
 	/** Add a callback to this class */

src/network/network_internal.h

@@ -161,7 +161,6 @@ void NetworkExecuteLocalCommandQueue();
 void NetworkFreeLocalCommandQueue();
 void NetworkSyncCommandQueue(NetworkClientSocket *cs);
 
-/* from network.c */
 void NetworkError(StringID error_string);
 void NetworkTextMessage(NetworkAction action, TextColour colour, bool self_send, const char *name, const char *str = "", int64 data = 0);
 uint NetworkCalculateLag(const NetworkClientSocket *cs);

src/newgrf_canal.cpp

@@ -97,6 +97,12 @@ static void NewCanalResolver(ResolverObject *res, TileIndex tile, const GRFFile
 }
 
 
+/**
+ * Lookup the base sprite to use for a canal.
+ * @param feature Which canal feature we want.
+ * @param tile Tile index of canal, if appropriate.
+ * @return Base sprite returned by GRF, or 0 if none.
+ */
 SpriteID GetCanalSprite(CanalFeature feature, TileIndex tile)
 {
 	ResolverObject object;

src/newgrf_canal.h

@@ -50,12 +50,6 @@ struct WaterFeature {
 extern WaterFeature _water_feature[CF_END];
 
 
-/**
- * Lookup the base sprite to use for a canal.
- * @param feature Which canal feature we want.
- * @param tile Tile index of canal, if appropriate.
- * @return Base sprite returned by GRF, or 0 if none.
- */
 SpriteID GetCanalSprite(CanalFeature feature, TileIndex tile);
 
 uint GetCanalSpriteOffset(CanalFeature feature, TileIndex tile, uint cur_offset);

src/newgrf_class.h

@@ -27,75 +27,18 @@ struct NewGRFClass {
 	/** The actual classes. */
 	static NewGRFClass<Tspec, Tid, Tmax> classes[Tmax];
 
-	/** Reset the classes, i.e. clear everything. */
 	static void Reset();
-
 	/** Initialise the defaults. */
 	static void InsertDefaults();
 
-	/**
-	 * Allocate a class with a given global class ID.
-	 * @param cls_id The global class id, such as 'DFLT'.
-	 * @return The (non global!) class ID for the class.
-	 * @note Upon allocating the same global class ID for a
-	 *       second time, this first allocation will be given.
-	 */
 	static Tid Allocate(uint32 global_id);
-
-	/**
-	 * Set the name of a particular class.
-	 * @param cls_id The id for the class.
-	 * @pre index < GetCount(cls_id)
-	 * @param name   The new name for the class.
-	 */
 	static void SetName(Tid cls_id, StringID name);
-
-	/**
-	 * Assign a spec to one of the classes.
-	 * @param spec The spec to assign.
-	 * @note The spec must have a valid class id set.
-	 */
 	static void Assign(Tspec *spec);
 
-
-	/**
-	 * Get the name of a particular class.
-	 * @param cls_id The class to get the name of.
-	 * @pre index < GetCount(cls_id)
-	 * @return The name of said class.
-	 */
 	static StringID GetName(Tid cls_id);
-
-	/**
-	 * Get the number of allocated classes.
-	 * @return The number of classes.
-	 */
 	static uint GetCount();
-
-	/**
-	 * Get the number of allocated specs within a particular class.
-	 * @param cls_id The class to get the size of.
-	 * @pre cls_id < GetCount()
-	 * @return The size of the class.
-	 */
 	static uint GetCount(Tid cls_id);
-
-	/**
-	 * Get a spec from a particular class at a given index.
-	 * @param cls_id The class to get the spec from.
-	 * @param index  The index where to find the spec.
-	 * @pre index < GetCount(cls_id)
-	 * @return The spec at given location.
-	 */
 	static const Tspec *Get(Tid cls_id, uint index);
-
-	/**
-	 * Retrieve a spec by GRF location.
-	 * @param grfid    GRF ID of spec.
-	 * @param local_id Index within GRF file of spec.
-	 * @param index    Pointer to return the index of the spec in its class. If NULL then not used.
-	 * @return The spec.
-	 */
 	static const Tspec *GetByGrf(uint32 grfid, byte local_id, int *index);
 };
 

src/newgrf_class_func.h

@@ -21,6 +21,7 @@
 template <typename Tspec, typename Tid, Tid Tmax>
 NewGRFClass<Tspec, Tid, Tmax> NewGRFClass<Tspec, Tid, Tmax>::classes[Tmax];
 
+/** Reset the classes, i.e. clear everything. */
 DEFINE_NEWGRF_CLASS_METHOD(void)::Reset()
 {
 	for (Tid i = (Tid)0; i < Tmax; i++) {
@@ -35,6 +36,13 @@ DEFINE_NEWGRF_CLASS_METHOD(void)::Reset()
 	InsertDefaults();
 }
 
+/**
+ * Allocate a class with a given global class ID.
+ * @param cls_id The global class id, such as 'DFLT'.
+ * @return The (non global!) class ID for the class.
+ * @note Upon allocating the same global class ID for a
+ *       second time, this first allocation will be given.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(Tid)::Allocate(uint32 global_id)
 {
 	for (Tid i = (Tid)0; i < Tmax; i++) {
@@ -52,12 +60,23 @@ DEFINE_NEWGRF_CLASS_METHOD(Tid)::Allocate(uint32 global_id)
 	return (Tid)0;
 }
 
+/**
+ * Set the name of a particular class.
+ * @param cls_id The id for the class.
+ * @pre index < GetCount(cls_id)
+ * @param name   The new name for the class.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(void)::SetName(Tid cls_id, StringID name)
 {
 	assert(cls_id < Tmax);
 	classes[cls_id].name = name;
 }
 
+/**
+ * Assign a spec to one of the classes.
+ * @param spec The spec to assign.
+ * @note The spec must have a valid class id set.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(void)::Assign(Tspec *spec)
 {
 	assert(spec->cls_id < Tmax);
@@ -69,12 +88,22 @@ DEFINE_NEWGRF_CLASS_METHOD(void)::Assign(Tspec *spec)
 	cls->spec[i] = spec;
 }
 
+/**
+ * Get the name of a particular class.
+ * @param cls_id The class to get the name of.
+ * @pre index < GetCount(cls_id)
+ * @return The name of said class.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(StringID)::GetName(Tid cls_id)
 {
 	assert(cls_id < Tmax);
 	return classes[cls_id].name;
 }
 
+/**
+ * Get the number of allocated classes.
+ * @return The number of classes.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(uint)::GetCount()
 {
 	uint i;
@@ -82,12 +111,25 @@ DEFINE_NEWGRF_CLASS_METHOD(uint)::GetCount()
 	return i;
 }
 
+/**
+ * Get the number of allocated specs within a particular class.
+ * @param cls_id The class to get the size of.
+ * @pre cls_id < GetCount()
+ * @return The size of the class.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(uint)::GetCount(Tid cls_id)
 {
 	assert(cls_id < Tmax);
 	return classes[cls_id].count;
 }
 
+/**
+ * Get a spec from a particular class at a given index.
+ * @param cls_id The class to get the spec from.
+ * @param index  The index where to find the spec.
+ * @pre index < GetCount(cls_id)
+ * @return The spec at given location.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(const Tspec *)::Get(Tid cls_id, uint index)
 {
 	assert(cls_id < Tmax);
@@ -97,6 +139,13 @@ DEFINE_NEWGRF_CLASS_METHOD(const Tspec *)::Get(Tid cls_id, uint index)
 	return NULL;
 }
 
+/**
+ * Retrieve a spec by GRF location.
+ * @param grfid    GRF ID of spec.
+ * @param local_id Index within GRF file of spec.
+ * @param index    Pointer to return the index of the spec in its class. If NULL then not used.
+ * @return The spec.
+ */
 DEFINE_NEWGRF_CLASS_METHOD(const Tspec *)::GetByGrf(uint32 grfid, byte local_id, int *index)
 {
 	uint j;

src/newgrf_debug.h

@@ -34,52 +34,13 @@ struct NewGrfDebugSpritePicker {
 
 extern NewGrfDebugSpritePicker _newgrf_debug_sprite_picker;
 
-/**
- * Can we inspect the data given a certain feature and index.
- * The index is normally an in-game location/identifier, such
- * as a TileIndex or an IndustryID depending on the feature
- * we want to inspect.
- * @param feature The feature we want to inspect.
- * @param index   The index/identifier of the feature to inspect.
- * @return true if there is something to show.
- */
 bool IsNewGRFInspectable(GrfSpecFeature feature, uint index);
-
-/**
- * Show the inspect window for a given feature and index.
- * The index is normally an in-game location/identifier, such
- * as a TileIndex or an IndustryID depending on the feature
- * we want to inspect.
- * @param feature The feature we want to inspect.
- * @param index   The index/identifier of the feature to inspect.
- */
 void ShowNewGRFInspectWindow(GrfSpecFeature feature, uint index);
-
-/**
- * Delete inspect window for a given feature and index.
- * The index is normally an in-game location/identifier, such
- * as a TileIndex or an IndustryID depending on the feature
- * we want to inspect.
- * @param feature The feature we want to delete the window for.
- * @param index   The index/identifier of the feature to delete.
- */
 void DeleteNewGRFInspectWindow(GrfSpecFeature feature, uint index);
 
-/**
- * Get the GrfSpecFeature associated with the tile.
- * @return the GrfSpecFeature.
- */
 GrfSpecFeature GetGrfSpecFeature(TileIndex tile);
-
-/**
- * Get the GrfSpecFeature associated with the vehicle.
- * @return the GrfSpecFeature.
- */
 GrfSpecFeature GetGrfSpecFeature(VehicleType type);
 
-/**
- * Show the window for aligning sprites.
- */
 void ShowSpriteAlignerWindow();
 
 #endif /* NEWGRF_DEBUG_H */

src/newgrf_debug_gui.cpp

@@ -487,6 +487,14 @@ static const WindowDesc _newgrf_inspect_desc(
 	_nested_newgrf_inspect_widgets, lengthof(_nested_newgrf_inspect_widgets)
 );
 
+/**
+ * Show the inspect window for a given feature and index.
+ * The index is normally an in-game location/identifier, such
+ * as a TileIndex or an IndustryID depending on the feature
+ * we want to inspect.
+ * @param feature The feature we want to inspect.
+ * @param index   The index/identifier of the feature to inspect.
+ */
 void ShowNewGRFInspectWindow(GrfSpecFeature feature, uint index)
 {
 	if (!IsNewGRFInspectable(feature, index)) return;
@@ -495,6 +503,14 @@ void ShowNewGRFInspectWindow(GrfSpecFeature feature, uint index)
 	AllocateWindowDescFront<NewGRFInspectWindow>(&_newgrf_inspect_desc, wno);
 }
 
+/**
+ * Delete inspect window for a given feature and index.
+ * The index is normally an in-game location/identifier, such
+ * as a TileIndex or an IndustryID depending on the feature
+ * we want to inspect.
+ * @param feature The feature we want to delete the window for.
+ * @param index   The index/identifier of the feature to delete.
+ */
 void DeleteNewGRFInspectWindow(GrfSpecFeature feature, uint index)
 {
 	if (feature == GSF_INVALID) return;
@@ -507,6 +523,15 @@ void DeleteNewGRFInspectWindow(GrfSpecFeature feature, uint index)
 	if (w != NULL) w->ReInit();
 }
 
+/**
+ * Can we inspect the data given a certain feature and index.
+ * The index is normally an in-game location/identifier, such
+ * as a TileIndex or an IndustryID depending on the feature
+ * we want to inspect.
+ * @param feature The feature we want to inspect.
+ * @param index   The index/identifier of the feature to inspect.
+ * @return true if there is something to show.
+ */
 bool IsNewGRFInspectable(GrfSpecFeature feature, uint index)
 {
 	const NIFeature *nif = GetFeature(GetInspectWindowNumber(feature, index));
@@ -514,6 +539,11 @@ bool IsNewGRFInspectable(GrfSpecFeature feature, uint index)
 	return nif->helper->IsInspectable(index);
 }
 
+/**
+ * Get the GrfSpecFeature associated with the tile.
+ * @param tile The tile to get the feature from.
+ * @return the GrfSpecFeature.
+ */
 GrfSpecFeature GetGrfSpecFeature(TileIndex tile)
 {
 	switch (GetTileType(tile)) {
@@ -533,6 +563,11 @@ GrfSpecFeature GetGrfSpecFeature(TileIndex tile)
 	}
 }
 
+/**
+ * Get the GrfSpecFeature associated with the vehicle.
+ * @param type The vehicle type to get the feature from.
+ * @return the GrfSpecFeature.
+ */
 GrfSpecFeature GetGrfSpecFeature(VehicleType type)
 {
 	switch (type) {
@@ -813,6 +848,9 @@ static const WindowDesc _sprite_aligner_desc(
 	_nested_sprite_aligner_widgets, lengthof(_nested_sprite_aligner_widgets)
 );
 
+/**
+ * Show the window for aligning sprites.
+ */
 void ShowSpriteAlignerWindow()
 {
 	AllocateWindowDescFront<SpriteAlignerWindow>(&_sprite_aligner_desc, 0);

src/newgrf_object.cpp

@@ -35,17 +35,31 @@ extern const ObjectSpec _original_objects[NEW_OBJECT_OFFSET];
 /** All the object specifications. */
 ObjectSpec _object_specs[NUM_OBJECTS];
 
+/**
+ * Get the specification associated with a specific ObjectType.
+ * @param index The object type to fetch.
+ * @return The specification.
+ */
 /* static */ const ObjectSpec *ObjectSpec::Get(ObjectType index)
 {
 	assert(index < NUM_OBJECTS);
 	return &_object_specs[index];
 }
 
+/**
+ * Get the specification associated with a tile.
+ * @param tile The tile to fetch the data for.
+ * @return The specification.
+ */
 /* static */ const ObjectSpec *ObjectSpec::GetByTile(TileIndex tile)
 {
 	return ObjectSpec::Get(GetObjectType(tile));
 }
 
+/**
+ * Check whether the object is available at this time.
+ * @return true if it is available.
+ */
 bool ObjectSpec::IsAvailable() const
 {
 	return this->enabled && _date > this->introduction_date &&
@@ -54,6 +68,10 @@ bool ObjectSpec::IsAvailable() const
 			(flags & (_game_mode != GM_EDITOR ? OBJECT_FLAG_ONLY_IN_SCENEDIT : OBJECT_FLAG_ONLY_IN_GAME)) == 0;
 }
 
+/**
+ * Gets the index of this spec.
+ * @return The index.
+ */
 uint ObjectSpec::Index() const
 {
 	return this - _object_specs;

src/newgrf_object.h

@@ -72,12 +72,6 @@ struct ObjectSpec {
 	uint8 views;                  ///< The number of views.
 	bool enabled;                 ///< Is this spec enabled?
 
-	/**
-	 * Check whether the object is available at this time.
-	 * @return true if it is available.
-	 */
-	bool IsAvailable() const;
-
 	/**
 	 * Get the cost for building a structure of this type.
 	 * @return The cost for building.
@@ -90,24 +84,10 @@ struct ObjectSpec {
 	 */
 	Money GetClearCost() const { return (_price[PR_CLEAR_OBJECT] * this->clear_cost_multiplier); }
 
-	/**
+	bool IsAvailable() const;
-	 * Gets the index of this spec.
-	 * @return The index.
-	 */
 	uint Index() const;
 
-	/**
-	 * Get the specification associated with a specific ObjectType.
-	 * @param index The object type to fetch.
-	 * @return The specification.
-	 */
 	static const ObjectSpec *Get(ObjectType index);
-
-	/**
-	 * Get the specification associated with a tile.
-	 * @param tile The tile to fetch the data for.
-	 * @return The specification.
-	 */
 	static const ObjectSpec *GetByTile(TileIndex tile);
 };
 

src/newgrf_storage.cpp

@@ -16,11 +16,27 @@
 /** The changed storage arrays */
 static std::set<BaseStorageArray*> _changed_storage_arrays;
 
+/**
+ * Add the changed storage array to the list of changed arrays.
+ * This is done so we only have to revert/save the changed
+ * arrays, which saves quite a few clears, etc. after callbacks.
+ * @param storage the array that has changed
+ */
 void AddChangedStorage(BaseStorageArray *storage)
 {
 	_changed_storage_arrays.insert(storage);
 }
 
+/**
+ * Clear the changes made since the last ClearStorageChanges.
+ * This is done for *all* storages that have been registered to with
+ * AddChangedStorage since the previous ClearStorageChanges.
+ *
+ * This can be done in two ways:
+ *  - saving the changes permanently
+ *  - reverting to the previous version
+ * @param keep_changes do we save or revert the changes since the last ClearChanges?
+ */
 void ClearStorageChanges(bool keep_changes)
 {
 	/* Loop over all changes arrays */

src/newgrf_storage.h

@@ -105,6 +105,10 @@ struct PersistentStorageArray : BaseStorageArray {
 		return this->storage[pos];
 	}
 
+	/**
+	 * Clear the changes, or assign them permanently to the storage.
+	 * @param keep_changes Whether to assign or ditch the changes.
+	 */
 	void ClearChanges(bool keep_changes)
 	{
 		assert(this->prev_storage != NULL);
@@ -166,25 +170,7 @@ struct TemporaryStorageArray : BaseStorageArray {
 	}
 };
 
-/**
- * Add the changed storage array to the list of changed arrays.
- * This is done so we only have to revert/save the changed
- * arrays, which saves quite a few clears, etc. after callbacks.
- * @param storage the array that has changed
- */
 void AddChangedStorage(BaseStorageArray *storage);
-
-
-/**
- * Clear the changes made since the last ClearStorageChanges.
- * This is done for *all* storages that have been registered to with
- * AddChangedStorage since the previous ClearStorageChanges.
- *
- * This can be done in two ways:
- *  - saving the changes permanently
- *  - reverting to the previous version
- * @param keep_changes do we save or revert the changes since the last ClearChanges?
- */
 void ClearStorageChanges(bool keep_changes);
 
 #endif /* NEWGRF_STORAGE_H */

src/news_func.h

@@ -51,17 +51,8 @@ extern bool _news_ticker_sound;
 
 extern NewsTypeData _news_type_data[];
 
-/**
- * Delete a news item type about a vehicle
- * if the news item type is INVALID_STRING_ID all news about the vehicle get
- * deleted
- */
 void DeleteVehicleNews(VehicleID vid, StringID news);
-
-/** Delete news associated with given station */
 void DeleteStationNews(StationID sid);
-
-/** Delete news associated with given station */
 void DeleteIndustryNews(IndustryID iid);
 
 #endif /* NEWS_FUNC_H */

src/news_gui.cpp

@@ -754,6 +754,12 @@ static void DeleteNewsItem(NewsItem *ni)
 	SetWindowDirty(WC_MESSAGE_HISTORY, 0);
 }
 
+/**
+ * Delete a news item type about a vehicle.
+ * When the news item type is INVALID_STRING_ID all news about the vehicle gets deleted.
+ * @param vid  The vehicle to remove the news for.
+ * @param news The news type to remove.
+ */
 void DeleteVehicleNews(VehicleID vid, StringID news)
 {
 	NewsItem *ni = _oldest_news;

src/saveload/newgrf_sl.cpp

@@ -24,6 +24,10 @@ static const SaveLoad _newgrf_mapping_desc[] = {
 	SLE_END()
 };
 
+/**
+ * Save a GRF ID + local id -> OpenTTD's id mapping.
+ * @param mapping The mapping to save.
+ */
 void Save_NewGRFMapping(const OverrideManagerBase &mapping)
 {
 	for (uint i = 0; i < mapping.GetMaxMapping(); i++) {
@@ -32,6 +36,10 @@ void Save_NewGRFMapping(const OverrideManagerBase &mapping)
 	}
 }
 
+/**
+ * Load a GRF ID + local id -> OpenTTD's id mapping.
+ * @param mapping The mapping to load.
+ */
 void Load_NewGRFMapping(OverrideManagerBase &mapping)
 {
 	/* Clear the current mapping stored.

src/saveload/newgrf_sl.h

@@ -14,16 +14,7 @@
 
 #include "../newgrf_commons.h"
 
-/**
- * Save a GRF ID + local id -> OpenTTD's id mapping.
- * @param mapping The mapping to save.
- */
 void Save_NewGRFMapping(const OverrideManagerBase &mapping);
-
-/**
- * Load a GRF ID + local id -> OpenTTD's id mapping.
- * @param mapping The mapping to load.
- */
 void Load_NewGRFMapping(OverrideManagerBase &mapping);
 
 #endif /* SAVELOAD_NEWGRF_SL_H */

src/spriteloader/grf.hpp

@@ -14,11 +14,9 @@
 
 #include "spriteloader.hpp"
 
+/** Sprite loader for graphics coming from a (New)GRF. */
 class SpriteLoaderGrf : public SpriteLoader {
 public:
-	/**
-	 * Load a sprite from the disk and return a sprite struct which is the same for all loaders.
-	 */
 	bool LoadSprite(SpriteLoader::Sprite *sprite, uint8 file_slot, size_t file_pos, SpriteType sprite_type);
 };
 

src/spriteloader/png.hpp

@@ -14,11 +14,9 @@
 
 #include "spriteloader.hpp"
 
+/** Sprite loader for graphics coming from a PNG image. */
 class SpriteLoaderPNG : public SpriteLoader {
 public:
-	/**
-	 * Load a sprite from the disk and return a sprite struct which is the same for all loaders.
-	 */
 	bool LoadSprite(SpriteLoader::Sprite *sprite, uint8 file_slot, size_t file_pos, SpriteType sprite_type);
 };
 

src/spriteloader/spriteloader.hpp

@@ -50,6 +50,11 @@ public:
 
 	/**
 	 * Load a sprite from the disk and return a sprite struct which is the same for all loaders.
+	 * @param sprite      The sprite to fill with data.
+	 * @param file_slot   The file "descriptor" of the file we read from.
+	 * @param file_pos    The position within the file the image begins.
+	 * @param sprite_type The type of sprite we're trying to load.
+	 * @return true iff loading went okay.
 	 */
 	virtual bool LoadSprite(SpriteLoader::Sprite *sprite, uint8 file_slot, size_t file_pos, SpriteType sprite_type) = 0;