(svn r22423) -Document: some network stuff

src/network/network.cpp

@@ -44,8 +44,10 @@
 bool _ddc_fastforward = true;
 #endif /* DEBUG_DUMP_COMMANDS */
 
+/** Make sure both pools have the same size. */
 assert_compile(NetworkClientInfoPool::MAX_SIZE == NetworkClientSocketPool::MAX_SIZE);
 
+/** The pool with client information. */
 NetworkClientInfoPool _networkclientinfo_pool("NetworkClientInfo");
 INSTANTIATE_POOL_METHODS(NetworkClientInfo)
 
@@ -54,30 +56,30 @@ bool _network_server;     ///< network-server is active
 bool _network_available;  ///< is network mode available?
 bool _network_dedicated;  ///< are we a dedicated server?
 bool _is_network_server;  ///< Does this client wants to be a network-server?
-NetworkServerGameInfo _network_game_info;
+NetworkServerGameInfo _network_game_info; ///< Information about our game.
-NetworkCompanyState *_network_company_states = NULL;
+NetworkCompanyState *_network_company_states = NULL; ///< Statistics about some companies.
-ClientID _network_own_client_id;
+ClientID _network_own_client_id;      ///< Our client identifier.
-ClientID _redirect_console_to_client;
+ClientID _redirect_console_to_client; ///< If not invalid, redirect the console output to a client.
-bool _network_need_advertise;
+bool _network_need_advertise;         ///< Whether we need to advertise.
-uint32 _network_last_advertise_frame;
+uint32 _network_last_advertise_frame; ///< Last time we did advertise.
-uint8 _network_reconnect;
+uint8 _network_reconnect;             ///< Reconnect timeout
-StringList _network_bind_list;
+StringList _network_bind_list;        ///< The addresses to bind on.
-StringList _network_host_list;
+StringList _network_host_list;        ///< The servers we know.
-StringList _network_ban_list;
+StringList _network_ban_list;         ///< The banned clients.
-uint32 _frame_counter_server; // The frame_counter of the server, if in network-mode
+uint32 _frame_counter_server;         ///< The frame_counter of the server, if in network-mode
-uint32 _frame_counter_max; // To where we may go with our clients
+uint32 _frame_counter_max;            ///< To where we may go with our clients
-uint32 _frame_counter;
+uint32 _frame_counter;                ///< The current frame.
-uint32 _last_sync_frame; // Used in the server to store the last time a sync packet was sent to clients.
+uint32 _last_sync_frame;              ///< Used in the server to store the last time a sync packet was sent to clients.
-NetworkAddressList _broadcast_list;
+NetworkAddressList _broadcast_list;   ///< List of broadcast addresses.
-uint32 _sync_seed_1;
+uint32 _sync_seed_1;                  ///< Seed to compare during sync checks.
 #ifdef NETWORK_SEND_DOUBLE_SEED
-uint32 _sync_seed_2;
+uint32 _sync_seed_2;                  ///< Second part of the seed.
 #endif
-uint32 _sync_frame;
+uint32 _sync_frame;                   ///< The frame to perform the sync check.
-bool _network_first_time;
+bool _network_first_time;             ///< Whether we have finished joining or not.
-bool _network_udp_server;
+bool _network_udp_server;             ///< Is the UDP server started?
-uint16 _network_udp_broadcast;
+uint16 _network_udp_broadcast;        ///< Timeout for the UDP broadcasts.
-uint8 _network_advertise_retries;
+uint8 _network_advertise_retries;     ///< The number of advertisement retries we did.
 CompanyMask _network_company_passworded; ///< Bitmask of the password status of all companies.
 
 /* Check whether NETWORK_NUM_LANDSCAPES is still in sync with NUM_LANDSCAPE */
@@ -88,7 +90,7 @@ extern NetworkUDPSocketHandler *_udp_client_socket; ///< udp client socket
 extern NetworkUDPSocketHandler *_udp_server_socket; ///< udp server socket
 extern NetworkUDPSocketHandler *_udp_master_socket; ///< udp master socket
 
-/* The amount of clients connected */
+/** The amount of clients connected */
 byte _network_clients_connected = 0;
 
 /* Some externs / forwards */

src/network/network_admin.cpp

@@ -33,6 +33,7 @@ AdminIndex _redirect_console_to_admin = INVALID_ADMIN_ID;
 /** The amount of admins connected. */
 byte _network_admins_connected = 0;
 
+/** The pool with sockets/clients. */
 NetworkAdminSocketPool _networkadminsocket_pool("NetworkAdminSocket");
 INSTANTIATE_POOL_METHODS(NetworkAdminSocket)
 
@@ -52,6 +53,7 @@ static const AdminUpdateFrequency _admin_update_type_frequencies[] = {
 	ADMIN_FREQUENCY_POLL,                                                                                                                                  ///< ADMIN_UPDATE_CMD_NAMES
 	                       ADMIN_FREQUENCY_AUTOMATIC,                                                                                                      ///< ADMIN_UPDATE_CMD_LOGGING
 };
+/** Sanity check. */
 assert_compile(lengthof(_admin_update_type_frequencies) == ADMIN_UPDATE_END);
 
 /**
@@ -655,7 +657,7 @@ NetworkRecvStatus ServerNetworkAdminSocketHandler::Receive_ADMIN_CHAT(Packet *p)
 
 /**
  * Notify the admin network of a new client (if they did opt in for the respective update).
- * @param ci the client info.
+ * @param cs the client info.
  * @param new_client if this is a new client, send the respective packet too.
  */
 void NetworkAdminClientInfo(const NetworkClientSocket *cs, bool new_client)

src/network/network_base.h

@@ -19,9 +19,11 @@
 #include "../core/pool_type.hpp"
 #include "../company_type.h"
 
+/** Type for the pool with client information. */
 typedef Pool<NetworkClientInfo, ClientIndex, 8, MAX_CLIENT_SLOTS, PT_NCLIENT> NetworkClientInfoPool;
 extern NetworkClientInfoPool _networkclientinfo_pool;
 
+/** Container for all information known about a client. */
 struct NetworkClientInfo : NetworkClientInfoPool::PoolItem<&_networkclientinfo_pool> {
 	ClientID client_id;                             ///< Client identifier (same as ClientState->client_id)
 	char client_name[NETWORK_CLIENT_NAME_LENGTH];   ///< Name of the client
@@ -29,13 +31,27 @@ struct NetworkClientInfo : NetworkClientInfoPool::PoolItem<&_networkclientinfo_p
 	CompanyID client_playas;                        ///< As which company is this client playing (CompanyID)
 	Date join_date;                                 ///< Gamedate the client has joined
 
+	/**
+	 * Create a new client.
+	 * @param client_id The unique identifier of the client.
+	 */
 	NetworkClientInfo(ClientID client_id = INVALID_CLIENT_ID) : client_id(client_id) {}
 	~NetworkClientInfo();
 
 	static NetworkClientInfo *GetByClientID(ClientID client_id);
 };
 
+/**
+ * Iterate over all the clients from a given index.
+ * @param var The variable to iterate with.
+ * @param start The location to start the iteration from.
+ */
 #define FOR_ALL_CLIENT_INFOS_FROM(var, start) FOR_ALL_ITEMS_FROM(NetworkClientInfo, clientinfo_index, var, start)
+
+/**
+ * Iterate over all the clients.
+ * @param var The variable to iterate with.
+ */
 #define FOR_ALL_CLIENT_INFOS(var) FOR_ALL_CLIENT_INFOS_FROM(var, 0)
 
 #endif /* ENABLE_NETWORK */

src/network/network_client.cpp

@@ -280,6 +280,7 @@ void ClientNetworkGameSocketHandler::ClientError(NetworkRecvStatus res)
 /** Our client's connection. */
 ClientNetworkGameSocketHandler * ClientNetworkGameSocketHandler::my_client = NULL;
 
+/** Last frame we performed an ack. */
 static uint32 last_ack_frame;
 
 /** One bit of 'entropy' used to generate a salt for the company passwords. */
@@ -308,6 +309,7 @@ assert_compile(NETWORK_SERVER_ID_LENGTH == 16 * 2 + 1);
  *   DEF_CLIENT_SEND_COMMAND has no parameters
  ************/
 
+/** Query the server for company information. */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendCompanyInformationQuery()
 {
 	my_client->status = STATUS_COMPANY_INFO;
@@ -319,6 +321,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendCompanyInformationQuery()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/** Tell the server we would like to join. */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendJoin()
 {
 	my_client->status = STATUS_JOIN;
@@ -334,6 +337,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendJoin()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/** Tell the server we got all the NewGRFs. */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendNewGRFsOk()
 {
 	Packet *p = new Packet(PACKET_CLIENT_NEWGRFS_CHECKED);
@@ -341,6 +345,10 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendNewGRFsOk()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Set the game password as requested.
+ * @param password The game password.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendGamePassword(const char *password)
 {
 	Packet *p = new Packet(PACKET_CLIENT_GAME_PASSWORD);
@@ -349,6 +357,10 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendGamePassword(const char *p
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Set the company password as requested.
+ * @param password The company password.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendCompanyPassword(const char *password)
 {
 	Packet *p = new Packet(PACKET_CLIENT_COMPANY_PASSWORD);
@@ -357,6 +369,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendCompanyPassword(const char
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/** Request the map from the server. */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendGetMap()
 {
 	my_client->status = STATUS_MAP_WAIT;
@@ -373,6 +386,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendGetMap()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/** Tell the server we received the complete map. */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendMapOk()
 {
 	my_client->status = STATUS_ACTIVE;
@@ -382,6 +396,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendMapOk()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/** Send an acknowledgement from the server's ticks. */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendAck()
 {
 	Packet *p = new Packet(PACKET_CLIENT_ACK);
@@ -392,7 +407,10 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendAck()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
-/* Send a command packet to the server */
+/**
+ * Send a command to the server.
+ * @param cp The command to send.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendCommand(const CommandPacket *cp)
 {
 	Packet *p = new Packet(PACKET_CLIENT_COMMAND);
@@ -402,7 +420,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendCommand(const CommandPacke
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
-/* Send a chat-packet over the network */
+/** Send a chat-packet over the network */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendChat(NetworkAction action, DestType type, int dest, const char *msg, int64 data)
 {
 	Packet *p = new Packet(PACKET_CLIENT_CHAT);
@@ -417,7 +435,7 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendChat(NetworkAction action,
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
-/* Send an error-packet over the network */
+/** Send an error-packet over the network */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendError(NetworkErrorCode errorno)
 {
 	Packet *p = new Packet(PACKET_CLIENT_ERROR);
@@ -427,6 +445,10 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendError(NetworkErrorCode err
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Tell the server that we like to change the password of the company.
+ * @param password The new password.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendSetPassword(const char *password)
 {
 	Packet *p = new Packet(PACKET_CLIENT_SET_PASSWORD);
@@ -436,6 +458,10 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendSetPassword(const char *pa
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Tell the server that we like to change the name of the client.
+ * @param name The new name.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendSetName(const char *name)
 {
 	Packet *p = new Packet(PACKET_CLIENT_SET_NAME);
@@ -445,6 +471,9 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendSetName(const char *name)
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Tell the server we would like to quit.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendQuit()
 {
 	Packet *p = new Packet(PACKET_CLIENT_QUIT);
@@ -453,6 +482,11 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendQuit()
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Send a console command.
+ * @param pass The password for the remote command.
+ * @param command The actual command.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendRCon(const char *pass, const char *command)
 {
 	Packet *p = new Packet(PACKET_CLIENT_RCON);
@@ -462,6 +496,11 @@ NetworkRecvStatus ClientNetworkGameSocketHandler::SendRCon(const char *pass, con
 	return NETWORK_RECV_STATUS_OKAY;
 }
 
+/**
+ * Ask the server to move us.
+ * @param company The company to move to.
+ * @param password The password of the company to move to.
+ */
 NetworkRecvStatus ClientNetworkGameSocketHandler::SendMove(CompanyID company, const char *password)
 {
 	Packet *p = new Packet(PACKET_CLIENT_MOVE);
@@ -1131,7 +1170,7 @@ void ClientNetworkGameSocketHandler::CheckConnection()
 }
 
 
-/* Is called after a client is connected to the server */
+/** Is called after a client is connected to the server */
 void NetworkClient_Connected()
 {
 	/* Set the frame-counter to 0 so nothing happens till we are ready */
@@ -1142,6 +1181,11 @@ void NetworkClient_Connected()
 	MyClient::SendJoin();
 }
 
+/**
+ * Send a remote console command.
+ * @param password The password.
+ * @param command The command to execute.
+ */
 void NetworkClientSendRcon(const char *password, const char *command)
 {
 	MyClient::SendRCon(password, command);
@@ -1158,6 +1202,10 @@ void NetworkClientRequestMove(CompanyID company_id, const char *pass)
 	MyClient::SendMove(company_id, pass);
 }
 
+/**
+ * Move the clients of a company to the spectators.
+ * @param cid The company to move the clients of.
+ */
 void NetworkClientsToSpectators(CompanyID cid)
 {
 	Backup<CompanyByte> cur_company(_current_company, FILE_LINE);
@@ -1174,6 +1222,9 @@ void NetworkClientsToSpectators(CompanyID cid)
 	cur_company.Restore();
 }
 
+/**
+ * Send the server our name.
+ */
 void NetworkUpdateClientName()
 {
 	NetworkClientInfo *ci = NetworkClientInfo::GetByClientID(_network_own_client_id);
@@ -1194,6 +1245,14 @@ void NetworkUpdateClientName()
 	}
 }
 
+/**
+ * Send a chat message.
+ * @param action The action associated with the message.
+ * @param type The destination type.
+ * @param dest The destination index, be it a company index or client id.
+ * @param msg The actual message.
+ * @param data Arbitrary extra data.
+ */
 void NetworkClientSendChat(NetworkAction action, DestType type, int dest, const char *msg, int64 data)
 {
 	MyClient::SendChat(action, type, dest, msg, data);

src/network/network_client.h

@@ -42,7 +42,7 @@ private:
 protected:
 	friend void NetworkExecuteLocalCommandQueue();
 	friend void NetworkClose(bool close_admins);
-	static ClientNetworkGameSocketHandler *my_client;
+	static ClientNetworkGameSocketHandler *my_client; ///< This is us!
 
 	virtual NetworkRecvStatus Receive_SERVER_FULL(Packet *p);
 	virtual NetworkRecvStatus Receive_SERVER_BANNED(Packet *p);
@@ -107,6 +107,7 @@ public:
 	static bool GameLoop();
 };
 
+/** Helper to make the code look somewhat nicer. */
 typedef ClientNetworkGameSocketHandler MyClient;
 
 void NetworkClient_Connected();

src/network/network_content.cpp

@@ -27,6 +27,8 @@
 #endif
 
 extern bool HasScenario(const ContentInfo *ci, bool md5sum);
+
+/** The client we use to connect to the server. */
 ClientNetworkContentSocketHandler _network_content_client;
 
 /** Wrapper function for the HasProc */
@@ -163,6 +165,10 @@ bool ClientNetworkContentSocketHandler::Receive_SERVER_INFO(Packet *p)
 	return true;
 }
 
+/**
+ * Request the content list for the given type.
+ * @param type The content type to request the list for.
+ */
 void ClientNetworkContentSocketHandler::RequestContentList(ContentType type)
 {
 	if (type == CONTENT_TYPE_END) {
@@ -188,6 +194,11 @@ void ClientNetworkContentSocketHandler::RequestContentList(ContentType type)
 	this->SendPacket(p);
 }
 
+/**
+ * Request the content list for a given number of content IDs.
+ * @param count The number of IDs to request.
+ * @param content_ids The unique identifiers of the content to request information about.
+ */
 void ClientNetworkContentSocketHandler::RequestContentList(uint count, const ContentID *content_ids)
 {
 	this->Connect();
@@ -213,6 +224,11 @@ void ClientNetworkContentSocketHandler::RequestContentList(uint count, const Con
 	}
 }
 
+/**
+ * Request the content list for a list of content.
+ * @param cv List with unique IDs and MD5 checksums.
+ * @param send_md5sum Whether we want a MD5 checksum matched set of files or not.
+ */
 void ClientNetworkContentSocketHandler::RequestContentList(ContentVector *cv, bool send_md5sum)
 {
 	if (cv == NULL) return;
@@ -258,6 +274,12 @@ void ClientNetworkContentSocketHandler::RequestContentList(ContentVector *cv, bo
 	}
 }
 
+/**
+ * Actually begin downloading the content we selected.
+ * @param[out] files The number of files we are going to download.
+ * @param[out] bytes The number of bytes we are going to download.
+ * @param fallback Whether to use the fallback or not.
+ */
 void ClientNetworkContentSocketHandler::DownloadSelectedContent(uint &files, uint &bytes, bool fallback)
 {
 	bytes = 0;
@@ -283,6 +305,10 @@ void ClientNetworkContentSocketHandler::DownloadSelectedContent(uint &files, uin
 	}
 }
 
+/**
+ * Initiate downloading the content over HTTP.
+ * @param content The content to download.
+ */
 void ClientNetworkContentSocketHandler::DownloadSelectedContentHTTP(const ContentIDList &content)
 {
 	uint count = content.Length();
@@ -307,6 +333,10 @@ void ClientNetworkContentSocketHandler::DownloadSelectedContentHTTP(const Conten
 	/* NetworkHTTPContentConnecter takes over freeing of content_request! */
 }
 
+/**
+ * Initiate downloading the content over the fallback protocol.
+ * @param content The content to download.
+ */
 void ClientNetworkContentSocketHandler::DownloadSelectedContentFallback(const ContentIDList &content)
 {
 	uint count = content.Length();
@@ -661,9 +691,7 @@ void ClientNetworkContentSocketHandler::OnReceiveData(const char *data, size_t l
 }
 
 /**
- * Create a socket handler with the given socket and (server) address.
+ * Create a socket handler to handle the connection.
- * @param s the socket to communicate over
- * @param sin the IP/port of the server
  */
 ClientNetworkContentSocketHandler::ClientNetworkContentSocketHandler() :
 	NetworkContentSocketHandler(),
@@ -683,8 +711,13 @@ ClientNetworkContentSocketHandler::~ClientNetworkContentSocketHandler()
 	for (ContentIterator iter = this->infos.Begin(); iter != this->infos.End(); iter++) delete *iter;
 }
 
+/** Connect to the content server. */
 class NetworkContentConnecter : TCPConnecter {
 public:
+	/**
+	 * Initiate the connecting.
+	 * @param address The address of the server.
+	 */
 	NetworkContentConnecter(const NetworkAddress &address) : TCPConnecter(address) {}
 
 	virtual void OnFailure()

src/network/network_content.h

@@ -19,10 +19,12 @@
 
 /** Vector with content info */
 typedef SmallVector<ContentInfo *, 16> ContentVector;
+/** Vector with constant content info */
 typedef SmallVector<const ContentInfo *, 16> ConstContentVector;
 
 /** Iterator for the content vector */
 typedef ContentInfo **ContentIterator;
+/** Iterator for the constant content vector */
 typedef const ContentInfo * const * ConstContentIterator;
 
 /** Callbacks for notifying others about incoming data */
@@ -66,7 +68,7 @@ struct ContentCallback {
  */
 class ClientNetworkContentSocketHandler : public NetworkContentSocketHandler, ContentCallback, HTTPCallback {
 protected:
-	typedef SmallVector<ContentID, 4> ContentIDList;
+	typedef SmallVector<ContentID, 4> ContentIDList; ///< List of content IDs to (possibly) select.
 	SmallVector<ContentCallback *, 2> callbacks; ///< Callbacks to notify "the world"
 	ContentIDList requested;                     ///< ContentIDs we already requested (so we don't do it again)
 	ContentVector infos;                         ///< All content info we received

src/network/network_content_gui.cpp

@@ -71,7 +71,6 @@ public:
 	/**
 	 * Create a new download window based on a list of content information
 	 * with flags whether to download them or not.
-	 * @param infos the list to search in
 	 */
 	NetworkContentDownloadStatusWindow() :
 		cur_id(UINT32_MAX)
@@ -221,23 +220,22 @@ enum NetworkContentListWindowWidgets {
 
 /** Window that lists the content that's at the content server */
 class NetworkContentListWindow : public QueryStringBaseWindow, ContentCallback {
+	/** List with content infos. */
 	typedef GUIList<const ContentInfo*> GUIContentList;
 
-	static const uint EDITBOX_MAX_SIZE   =  50;
+	static const uint EDITBOX_MAX_SIZE   =  50; ///< Maximum size of the editbox in characters.
-	static const uint EDITBOX_MAX_LENGTH = 300;
+	static const uint EDITBOX_MAX_LENGTH = 300; ///< Maximum size of the editbox in pixels.
 
-	/** Runtime saved values */
+	static Listing last_sorting;     ///< The last sorting setting.
-	static Listing last_sorting;
+	static Filtering last_filtering; ///< The last filtering setting.
-	static Filtering last_filtering;
+	static GUIContentList::SortFunction * const sorter_funcs[];   ///< Sorter functions
-	/** The sorter functions */
+	static GUIContentList::FilterFunction * const filter_funcs[]; ///< Filter functions.
-	static GUIContentList::SortFunction * const sorter_funcs[];
-	static GUIContentList::FilterFunction * const filter_funcs[];
 	GUIContentList content;      ///< List with content
 
 	const ContentInfo *selected; ///< The selected content info
 	int list_pos;                ///< Our position in the list
 	uint filesize_sum;           ///< The sum of all selected file sizes
-	Scrollbar *vscroll;
+	Scrollbar *vscroll;          ///< Cache of the vertical scrollbar
 
 	/**
 	 * (Re)build the network game list as its amount has changed because
@@ -344,6 +342,7 @@ public:
 	/**
 	 * Create the content list window.
 	 * @param desc the window description to pass to Window's constructor.
+	 * @param select_all Whether the select all button is allowed or not.
 	 */
 	NetworkContentListWindow(const WindowDesc *desc, bool select_all) :
 			QueryStringBaseWindow(EDITBOX_MAX_SIZE),
@@ -438,6 +437,10 @@ public:
 		}
 	}
 
+	/**
+	 * Draw/fill the matrix with the list of content to download.
+	 * @param r The boundaries of the matrix.
+	 */
 	void DrawMatrix(const Rect &r) const
 	{
 		const NWidgetBase *nwi_checkbox = this->GetWidget<NWidgetBase>(NCLWW_CHECKBOX);
@@ -806,6 +809,7 @@ NetworkContentListWindow::GUIContentList::FilterFunction * const NetworkContentL
 	&TagNameFilter,
 };
 
+/** The widgets for the content list. */
 static const NWidgetPart _nested_network_content_list_widgets[] = {
 	NWidget(NWID_HORIZONTAL),
 		NWidget(WWT_CLOSEBOX, COLOUR_LIGHT_BLUE),

src/network/network_udp.cpp

@@ -34,6 +34,7 @@
 
 #include "core/udp.h"
 
+/** Mutex for all out threaded udp resoltion and such. */
 static ThreadMutex *_network_udp_mutex = ThreadMutex::New();
 
 /** Session key to register ourselves to the master server */
@@ -49,11 +50,16 @@ NetworkUDPSocketHandler *_udp_master_socket = NULL; ///< udp master socket
 
 ///*** Communication with the masterserver ***/
 
+/** Helper class for connecting to the master server. */
 class MasterNetworkUDPSocketHandler : public NetworkUDPSocketHandler {
 protected:
 	virtual void Receive_MASTER_ACK_REGISTER(Packet *p, NetworkAddress *client_addr);
 	virtual void Receive_MASTER_SESSION_KEY(Packet *p, NetworkAddress *client_addr);
 public:
+	/**
+	 * Create the socket.
+	 * @param addresses The addresses to bind on.
+	 */
 	MasterNetworkUDPSocketHandler(NetworkAddressList *addresses) : NetworkUDPSocketHandler(addresses) {}
 	virtual ~MasterNetworkUDPSocketHandler() {}
 };
@@ -75,12 +81,17 @@ void MasterNetworkUDPSocketHandler::Receive_MASTER_SESSION_KEY(Packet *p, Networ
 
 ///*** Communication with clients (we are server) ***/
 
+/** Helper class for handling all server side communication. */
 class ServerNetworkUDPSocketHandler : public NetworkUDPSocketHandler {
 protected:
 	virtual void Receive_CLIENT_FIND_SERVER(Packet *p, NetworkAddress *client_addr);
 	virtual void Receive_CLIENT_DETAIL_INFO(Packet *p, NetworkAddress *client_addr);
 	virtual void Receive_CLIENT_GET_NEWGRFS(Packet *p, NetworkAddress *client_addr);
 public:
+	/**
+	 * Create the socket.
+	 * @param addresses The addresses to bind on.
+	 */
 	ServerNetworkUDPSocketHandler(NetworkAddressList *addresses) : NetworkUDPSocketHandler(addresses) {}
 	virtual ~ServerNetworkUDPSocketHandler() {}
 };
@@ -246,6 +257,7 @@ void ServerNetworkUDPSocketHandler::Receive_CLIENT_GET_NEWGRFS(Packet *p, Networ
 
 ///*** Communication with servers (we are client) ***/
 
+/** Helper class for handling all client side communication. */
 class ClientNetworkUDPSocketHandler : public NetworkUDPSocketHandler {
 protected:
 	virtual void Receive_SERVER_RESPONSE(Packet *p, NetworkAddress *client_addr);
@@ -413,7 +425,7 @@ void ClientNetworkUDPSocketHandler::HandleIncomingNetworkGameInfoGRFConfig(GRFCo
 	SetBit(config->flags, GCF_COPY);
 }
 
-/* Broadcast to all ips */
+/** Broadcast to all ips */
 static void NetworkUDPBroadCast(NetworkUDPSocketHandler *socket)
 {
 	for (NetworkAddress *addr = _broadcast_list.Begin(); addr != _broadcast_list.End(); addr++) {
@@ -426,7 +438,7 @@ static void NetworkUDPBroadCast(NetworkUDPSocketHandler *socket)
 }
 
 
-/* Request the the server-list from the master server */
+/** Request the the server-list from the master server */
 void NetworkUDPQueryMasterServer()
 {
 	Packet p(PACKET_UDP_CLIENT_GET_LIST);
@@ -441,7 +453,7 @@ void NetworkUDPQueryMasterServer()
 	DEBUG(net, 2, "[udp] master server queried at %s", out_addr.GetAddressAsString());
 }
 
-/* Find all servers */
+/** Find all servers */
 void NetworkUDPSearchGame()
 {
 	/* We are still searching.. */
@@ -456,6 +468,12 @@ void NetworkUDPSearchGame()
 /** Simpler wrapper struct for NetworkUDPQueryServerThread */
 struct NetworkUDPQueryServerInfo : NetworkAddress {
 	bool manually; ///< Did we connect manually or not?
+
+	/**
+	 * Create the structure.
+	 * @param address The address of the server to query.
+	 * @param manually Whether the address was entered manually.
+	 */
 	NetworkUDPQueryServerInfo(const NetworkAddress &address, bool manually) :
 		NetworkAddress(address),
 		manually(manually)
@@ -488,6 +506,11 @@ static void NetworkUDPQueryServerThread(void *pntr)
 	delete info;
 }
 
+/**
+ * Query a specific server.
+ * @param address The address of the server.
+ * @param manually Whether the address was entered manually.
+ */
 void NetworkUDPQueryServer(NetworkAddress address, bool manually)
 {
 	NetworkUDPQueryServerInfo *info = new NetworkUDPQueryServerInfo(address, manually);
@@ -496,6 +519,10 @@ void NetworkUDPQueryServer(NetworkAddress address, bool manually)
 	}
 }
 
+/**
+ * Thread entry point for de-advertising.
+ * @param pntr unused.
+ */
 static void NetworkUDPRemoveAdvertiseThread(void *pntr)
 {
 	DEBUG(net, 1, "[udp] removing advertise from master server");
@@ -528,6 +555,10 @@ void NetworkUDPRemoveAdvertise(bool blocking)
 	}
 }
 
+/**
+ * Thread entry point for advertising.
+ * @param pntr unused.
+ */
 static void NetworkUDPAdvertiseThread(void *pntr)
 {
 	/* Find somewhere to send */
@@ -564,8 +595,10 @@ static void NetworkUDPAdvertiseThread(void *pntr)
 	_network_udp_mutex->EndCritical();
 }
 
-/* Register us to the master server
+/**
- *   This function checks if it needs to send an advertise */
+ * Register us to the master server
+ *   This function checks if it needs to send an advertise
+ */
 void NetworkUDPAdvertise()
 {
 	/* Check if we should send an advertise */
@@ -593,6 +626,7 @@ void NetworkUDPAdvertise()
 	}
 }
 
+/** Initialize the whole UDP bit. */
 void NetworkUDPInitialize()
 {
 	/* If not closed, then do it. */
@@ -618,6 +652,7 @@ void NetworkUDPInitialize()
 	_network_udp_mutex->EndCritical();
 }
 
+/** Close all UDP related stuff. */
 void NetworkUDPClose()
 {
 	_network_udp_mutex->BeginCritical();

src/openttd.cpp

@@ -69,6 +69,7 @@
 
 #include "table/strings.h"
 
+/** Error message to show when switching modes. */
 StringID _switch_mode_errorstr;
 
 void CallLandscapeTick();

src/querystring_gui.h

@@ -78,7 +78,17 @@ struct QueryStringBaseWindow : public Window, public QueryString {
 	void DrawEditBox(int wid);
 	void HandleEditBox(int wid);
 	HandleEditBoxResult HandleEditBoxKey(int wid, uint16 key, uint16 keycode, EventState &state);
+
+	/**
+	 * Callback for when the OSK window is opened.
+	 * @param wid The widget the OSK is opened of.
+	 */
 	virtual void OnOpenOSKWindow(int wid);
+
+	/**
+	 * Callback for when on input has been entered with the OSK.
+	 * @param wid The widget the OSK was attached to.
+	 */
 	virtual void OnOSKInput(int wid) {}
 };