(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