Recast: Detail API documentation covering the elements declared in RecastAlloc.h.

Recast/Include/RecastAlloc.h

@@ -19,23 +19,43 @@
 #ifndef RECASTALLOC_H
 #define RECASTALLOC_H
 
+/// Provides hint values to the memory allocator on how long the
+/// memory is expected to be used.
 enum rcAllocHint
 {
-	RC_ALLOC_PERM,		///< Memory persist after a function call.
+	RC_ALLOC_PERM,		///< Memory will persist after a function call.
 	RC_ALLOC_TEMP		///< Memory used temporarily within a function.
 };
 
+/// A memory allocation function.
+//  @param[in] size         The size, in bytes of memory, to allocate.
+//  @param[in] rcAllocHint  A hint to the allocator on how long the memory is expected to be in use.
+//  @return A pointer to the beginning of the allocated memory block, or null if the allocation failed.
+///  @see rcAllocSetCustom
 typedef void* (rcAllocFunc)(int size, rcAllocHint hint);
+
+/// A memory deallocation function.
+/// @see rcAllocSetCustom
+//  @param[in] ptr 
 typedef void (rcFreeFunc)(void* ptr);
 
+/// Sets the custom allocation functions to be used by Recast.
+///  @param[in] allocFunc  The memory allocation function to be used by #rcAlloc
+///  @param[in] freeFunc   The memory de-allocation function to be used by #rcFree
 void rcAllocSetCustom(rcAllocFunc *allocFunc, rcFreeFunc *freeFunc);
 
+/// Allocates a memory block.
+///  @param[in] size  The size, in bytes of memory, to allocate.
+///  @param[in] hint  A hint to the allocator on how long the memory is expected to be in use.
+///  @return A pointer to the beginning of the allocated memory block, or null if the allocation failed.
 void* rcAlloc(int size, rcAllocHint hint);
+
+/// Deallocates a memory block.
+///  @param[in] ptr A pointer to a memory block previously allocated using #rcAlloc.
 void rcFree(void* ptr);
 
 
-
+/// A simple dynamic array of integers.
-/// Simple dynamic array ints.
 class rcIntArray
 {
 	int* m_data;
@@ -43,26 +63,59 @@ class rcIntArray
 	inline rcIntArray(const rcIntArray&);
 	inline rcIntArray& operator=(const rcIntArray&);
 public:
+
+	/// Constructs an instance with an initial array size of zero.
 	inline rcIntArray() : m_data(0), m_size(0), m_cap(0) {}
+
+	/// Constructs an instance initialized to the specified size.
+	///  @param[in] n The initial size of the integer array.
 	inline rcIntArray(int n) : m_data(0), m_size(0), m_cap(0) { resize(n); }
 	inline ~rcIntArray() { rcFree(m_data); }
+
+	/// Specifies the new size of the integer array.
+	///  @param[in] n  The new size of the integer array.
 	void resize(int n);
+
+	/// Push the specified integer onto the end of the array and increases the size by one.
+	///  @param[in] item  The new value.
 	inline void push(int item) { resize(m_size+1); m_data[m_size-1] = item; }
+
+	/// Returns the value at the end of the array and reduces the size by one.
+	///  @return The value at the end of the array.
 	inline int pop() { if (m_size > 0) m_size--; return m_data[m_size]; }
+
+	/// The value at the specified array index.
+	/// @warning Does not provide overflow protection.
+	///  @param[in] i  The index of the value.
 	inline const int& operator[](int i) const { return m_data[i]; }
+
+	/// The value at the specified array index.
+	/// @warning Does not provide overflow protection.
+	///  @param[in] i  The index of the value.
 	inline int& operator[](int i) { return m_data[i]; }
+
+	/// The current size of the integer array.
 	inline int size() const { return m_size; }
 };
 
-/// Simple internal helper class to delete array in scope
+/// A simple helper class used to delete an array when it goes out of scope.
+/// @note This class is rarely if ever used by the end user.
 template<class T> class rcScopedDelete
 {
 	T* ptr;
 	inline T* operator=(T* p);
 public:
+
+	/// Constructs an instance with a null pointer.
 	inline rcScopedDelete() : ptr(0) {}
+
+	/// Constructs an instance with the specified pointer.
+	///  @param[in] p  An pointer to an allocated array.
 	inline rcScopedDelete(T* p) : ptr(p) {}
 	inline ~rcScopedDelete() { rcFree(ptr); }
+
+	/// The root array pointer.
+	///  @return The root array pointer.
 	inline operator T*() { return ptr; }
 };
 

Recast/Source/RecastAlloc.cpp

@@ -33,24 +33,45 @@ static void rcFreeDefault(void *ptr)
 static rcAllocFunc* sRecastAllocFunc = rcAllocDefault;
 static rcFreeFunc* sRecastFreeFunc = rcFreeDefault;
 
+/// @see rcAlloc, rcFree
 void rcAllocSetCustom(rcAllocFunc *allocFunc, rcFreeFunc *freeFunc)
 {
 	sRecastAllocFunc = allocFunc ? allocFunc : rcAllocDefault;
 	sRecastFreeFunc = freeFunc ? freeFunc : rcFreeDefault;
 }
 
+/// @see rcAllocSetCustom
 void* rcAlloc(int size, rcAllocHint hint)
 {
 	return sRecastAllocFunc(size, hint);
 }
 
+/// @par
+///
+/// @warning This function leaves the value of @p ptr unchanged.  So it still
+/// points to the same (now invalid) location, and not to null.
+/// 
+/// @see rcAllocSetCustom
 void rcFree(void* ptr)
 {
 	if (ptr)
 		sRecastFreeFunc(ptr);
 }
 
+/// @class rcIntArray
+///
+/// While it is possible to pre-allocate a specific array size during 
+/// construction or by using the #resize method, certain methods will 
+/// automatically resize the array as needed.
+///
+/// @warning The array memory is not initialized to zero when the size is 
+/// manually set during construction or when using #resize.
 
+/// @par
+///
+/// Using this method ensures the array is at least large enough to hold
+/// the specified number of elements.  This can improve performance by
+/// avoiding auto-resizing during use.
 void rcIntArray::resize(int n)
 {
 	if (n > m_cap)