Mercurial > hg > openttd
changeset 17148:848eb1ffb17d draft
(svn r21886) -Codechange: move documentation towards the code to make it more likely to be updated [n].
line wrap: on
line diff
--- a/src/core/alloc_func.hpp +++ b/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);
--- a/src/core/pool_func.hpp +++ b/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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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;
--- a/src/core/pool_type.hpp +++ b/src/core/pool_type.hpp @@ -37,9 +37,7 @@ 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 @@ /** 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); };
--- a/src/core/random_func.cpp +++ b/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 @@ 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);
--- a/src/core/random_func.hpp +++ b/src/core/random_func.hpp @@ -37,23 +37,8 @@ /** 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
--- a/src/network/core/address.cpp +++ b/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 @@ return this->hostname; } +/** + * Get the port. + * @return the port. + */ uint16 NetworkAddress::GetPort() const { switch (this->address.ss_family) { @@ -40,6 +49,10 @@ } } +/** + * Set the port. + * @param port set the port number. + */ void NetworkAddress::SetPort(uint16 port) { switch (this->address.ss_family) { @@ -57,6 +70,12 @@ } } +/** + * 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 @@ } } +/** + * 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ } } +/** + * 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 @@ } } +/** + * 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) {
--- a/src/network/core/address.h +++ b/src/network/core/address.h @@ -41,15 +41,6 @@ */ 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 @@ 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 @@ 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 @@ 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 @@ 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); };
--- a/src/network/core/tcp.h +++ b/src/network/core/tcp.h @@ -58,13 +58,8 @@ 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 @@ 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 @@ */ 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(); };
--- a/src/network/core/tcp_connect.cpp +++ b/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 @@ } } +/** The actual connection function */ void TCPConnecter::Connect() { this->sock = this->address.Connect(); @@ -44,12 +49,21 @@ } } - +/** + * 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 @@ } } +/** Kill all connection attempts. */ /* static */ void TCPConnecter::KillAll() { for (TCPConnecter **iter = _tcp_connecters.Begin(); iter != _tcp_connecters.End(); iter++) (*iter)->killed = true;
--- a/src/network/core/tcp_content.cpp +++ b/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 @@ } } +/** + * 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 @@ 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 @@ } } +/** + * 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 @@ #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) {
--- a/src/network/core/tcp_content.h +++ b/src/network/core/tcp_content.h @@ -82,30 +82,13 @@ 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 @@ */ 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 @@ /** On destructing of this class, the socket needs to be closed */ virtual ~NetworkContentSocketHandler() { this->Close(); } - /** Do the actual receiving of packets. */ void ReceivePackets(); };
--- a/src/network/core/tcp_http.cpp +++ b/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 @@ *_http_connections.Append() = this; } +/** Free whatever needs to be freed. */ NetworkHTTPSocketHandler::~NetworkHTTPSocketHandler() { this->CloseConnection(); @@ -175,6 +184,13 @@ 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 @@ } } +/** + * Do the receiving for all HTTP connections. + */ /* static */ void NetworkHTTPSocketHandler::HTTPReceive() { /* No connections, just bail out. */
--- a/src/network/core/tcp_http.h +++ b/src/network/core/tcp_http.h @@ -64,33 +64,14 @@ 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(); };
--- a/src/network/network_content.cpp +++ b/src/network/network_content.cpp @@ -982,6 +982,7 @@ } } +/** Clear all downloaded content information. */ void ClientNetworkContentSocketHandler::Clear() { for (ContentIterator iter = this->infos.Begin(); iter != this->infos.End(); iter++) delete *iter;
--- a/src/network/network_content.h +++ b/src/network/network_content.h @@ -136,7 +136,7 @@ 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 */
--- a/src/network/network_internal.h +++ b/src/network/network_internal.h @@ -161,7 +161,6 @@ 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);
--- a/src/newgrf_canal.cpp +++ b/src/newgrf_canal.cpp @@ -97,6 +97,12 @@ } +/** + * 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;
--- a/src/newgrf_canal.h +++ b/src/newgrf_canal.h @@ -50,12 +50,6 @@ 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);
--- a/src/newgrf_class.h +++ b/src/newgrf_class.h @@ -27,75 +27,18 @@ /** 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); };
--- a/src/newgrf_class_func.h +++ b/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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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;
--- a/src/newgrf_debug.h +++ b/src/newgrf_debug.h @@ -34,52 +34,13 @@ 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 */
--- a/src/newgrf_debug_gui.cpp +++ b/src/newgrf_debug_gui.cpp @@ -487,6 +487,14 @@ _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 @@ 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 @@ 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 @@ 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 @@ } } +/** + * 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 @@ _nested_sprite_aligner_widgets, lengthof(_nested_sprite_aligner_widgets) ); +/** + * Show the window for aligning sprites. + */ void ShowSpriteAlignerWindow() { AllocateWindowDescFront<SpriteAlignerWindow>(&_sprite_aligner_desc, 0);
--- a/src/newgrf_object.cpp +++ b/src/newgrf_object.cpp @@ -35,17 +35,31 @@ /** 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 @@ (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;
--- a/src/newgrf_object.h +++ b/src/newgrf_object.h @@ -73,12 +73,6 @@ 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 @@ */ Money GetClearCost() const { return (_price[PR_CLEAR_OBJECT] * this->clear_cost_multiplier); } - /** - * Gets the index of this spec. - * @return The index. - */ + bool IsAvailable() const; 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); };
--- a/src/newgrf_storage.cpp +++ b/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 */
--- a/src/newgrf_storage.h +++ b/src/newgrf_storage.h @@ -105,6 +105,10 @@ 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 @@ } }; -/** - * 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 */
--- a/src/news_func.h +++ b/src/news_func.h @@ -51,17 +51,8 @@ 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 */
--- a/src/news_gui.cpp +++ b/src/news_gui.cpp @@ -754,6 +754,12 @@ 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;
--- a/src/saveload/newgrf_sl.cpp +++ b/src/saveload/newgrf_sl.cpp @@ -24,6 +24,10 @@ 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 @@ } } +/** + * 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.
--- a/src/saveload/newgrf_sl.h +++ b/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 */
--- a/src/spriteloader/grf.hpp +++ b/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); };
--- a/src/spriteloader/png.hpp +++ b/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); };
--- a/src/spriteloader/spriteloader.hpp +++ b/src/spriteloader/spriteloader.hpp @@ -50,6 +50,11 @@ /** * 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;