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

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.
- * @param p the received packet
+ * 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 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);