Fix docs for List and Queue

src/core/containers/List.h

@@ -33,41 +33,73 @@ OTHER DEALINGS IN THE SOFTWARE.
 namespace crown
 {
 
-/**
-	Dynamic array of POD items.
-@note
-	Does not call constructors/destructors so it is not very suitable for non-POD items.
-*/
+/// Dynamic array of POD items.
+/// @note
+/// Does not call constructors/destructors so it is not very suitable for non-POD items.
 template <typename T>
 class List
 {
 public:
 
 						List(Allocator& allocator);
+
+	/// Allocates capacity * sizeof(T) bytes.
 						List(Allocator& allocator, uint32_t capacity);
 						List(const List<T>& list);
 						~List();
 
+	/// Random access by index
 	T&					operator[](uint32_t index);
+
+	/// Random access by index
 	const T&			operator[](uint32_t index) const;
 
+	/// Returns whether the list is empty
 	bool				empty() const;
+
+	/// Returns the number of items in the list
 	uint32_t			size() const;
+
+	/// Returns the maximum number of items the array can hold
 	uint32_t			capacity() const;
+
+	/// Resizes the list to the given @size.
+	/// @note
+	/// Old items will be copied to the newly created list.
+	/// If the new capacity is smaller than the previous one, the
+	/// list will be truncated.
 	void				resize(uint32_t size);
+
+	/// Reserves space in the list for at least @capacity items.
 	void				reserve(uint32_t capacity);
+
+	/// Sets the list capacity
 	void				set_capacity(uint32_t capacity);
+
+	/// Grows the list to contain at least @min_capacity items
 	void				grow(uint32_t min_capacity);
 
+	/// Condenses the array so that the capacity matches the actual number
+	/// of items in the list.
 	void				condense();
 
+	/// Appends an item to the list and returns its index.
 	uint32_t			push_back(const T& item);
+
+	/// Removes the last item from the list.
 	void				pop_back();
 
-	uint32_t			push(const T* items, uint32_t num_items);
+	/// Appends @count @items to the list and returns the number
+	/// of items in the list after the append operation.
+	uint32_t			push(const T* items, uint32_t count);
 
+	/// Clears the content of the list.
+	/// @note
+	/// Does not free memory nor call destructors, it only zeroes
+	/// the number of items in the list for efficiency.
 	void				clear();
 
+	/// Copies the content of the @other list into this one.
 	const List<T>&		operator=(const List<T>& other);
 
 	T*					begin();
@@ -82,34 +114,26 @@ public:
 
 private:
 
-	Allocator*			m_allocator;
+	Allocator&			m_allocator;
 	uint32_t			m_capacity;
 	uint32_t			m_size;
 	T*					m_array;
 };
 
-/**
-	Constructor.
-@note
-	Does not allocate memory.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline List<T>::List(Allocator& allocator) :
-	m_allocator(&allocator),
+	m_allocator(allocator),
 	m_capacity(0),
 	m_size(0),
 	m_array(NULL)
 {
 }
 
-/**
-	Constructor.
-@note
-	Allocates capacity * sizeof(T) bytes.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline List<T>::List(Allocator& allocator, uint32_t capacity) :
-	m_allocator(&allocator),
+	m_allocator(allocator),
 	m_capacity(0),
 	m_size(0),
 	m_array(NULL)
@@ -117,9 +141,7 @@ inline List<T>::List(Allocator& allocator, uint32_t capacity) :
 	resize(capacity);
 }
 
-/**
-	Copy constructor.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline List<T>::List(const List<T>& list) :
 	m_capacity(0),
@@ -129,23 +151,17 @@ inline List<T>::List(const List<T>& list) :
 	*this = list;
 }
 
-/**
-	Destructor.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline List<T>::~List()
 {
 	if (m_array)
 	{
-		m_allocator->deallocate(m_array);
+		m_allocator.deallocate(m_array);
 	}
 }
 
-/**
-	Random access.
-@note
-	The index has to be smaller than size()
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline T& List<T>::operator[](uint32_t index)
 {
@@ -154,11 +170,7 @@ inline T& List<T>::operator[](uint32_t index)
 	return m_array[index];
 }
 
-/**
-	Random access.
-@note
-	The index has to be smaller than size()
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline const T& List<T>::operator[](uint32_t index) const
 {
@@ -167,40 +179,28 @@ inline const T& List<T>::operator[](uint32_t index) const
 	return m_array[index];
 }
 
-/**
-	Returns whether the array is empty.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline bool List<T>::empty() const
 {
 	return m_size == 0;
 }
 
-/**
-	Returns the number of items in the array.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline uint32_t List<T>::size() const
 {
 	return m_size;
 }
 
-/**
-	Returns the maximum number of items the array can hold.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline uint32_t List<T>::capacity() const
 {
 	return m_capacity;
 }
 
-/**
-	Resizes the array to the given size.
-@note
-	Old items will be copied to the newly created array.
-	If the new capacity is smaller than the previous one, the
-	array will be truncated.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::resize(uint32_t size)
 {
@@ -212,9 +212,7 @@ inline void List<T>::resize(uint32_t size)
 	m_size = size;
 }
 
-/**
-	Reserves space in the array for at least capacity items.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::reserve(uint32_t capacity)
 {
@@ -224,9 +222,7 @@ inline void List<T>::reserve(uint32_t capacity)
 	}
 }
 
-/**
-	Sets the array capacity
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::set_capacity(uint32_t capacity)
 {
@@ -245,20 +241,18 @@ inline void List<T>::set_capacity(uint32_t capacity)
 		T* tmp = m_array;
 		m_capacity = capacity;
 
-		m_array = (T*)m_allocator->allocate(capacity * sizeof(T));
+		m_array = (T*)m_allocator.allocate(capacity * sizeof(T));
 
 		memcpy(m_array, tmp, m_size * sizeof(T));
 
 		if (tmp)
 		{
-			m_allocator->deallocate(tmp);
+			m_allocator.deallocate(tmp);
 		}
 	}
 }
 
-/**
-	Grows the array to contain at least min_capacity items
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::grow(uint32_t min_capacity)
 {
@@ -272,19 +266,14 @@ inline void List<T>::grow(uint32_t min_capacity)
 	set_capacity(new_capacity);
 }
 
-/**
-	Condenses the array so the capacity matches the actual number
-	of items in the array.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::condense()
 {
 	resize(m_size);
 }
 
-/**
-	Appends an item to the array and returns its index.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline uint32_t List<T>::push_back(const T& item)
 {
@@ -298,9 +287,7 @@ inline uint32_t List<T>::push_back(const T& item)
 	return 	m_size++;
 }
 
-/**
-	Removes the item at the given index.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::pop_back()
 {
@@ -309,41 +296,35 @@ inline void List<T>::pop_back()
 	m_size--;
 }
 
+//-----------------------------------------------------------------------------
 template <typename T>
-inline uint32_t List<T>::push(const T* items, uint32_t num_items)
+inline uint32_t List<T>::push(const T* items, uint32_t count)
 {
-	if (m_capacity <= m_size + num_items)
+	if (m_capacity <= m_size + count)
 	{
-		grow(m_size + num_items);
+		grow(m_size + count);
 	}
 
-	memcpy(&m_array[m_size], items, sizeof(T) * num_items);
-	m_size += num_items;
+	memcpy(&m_array[m_size], items, sizeof(T) * count);
+	m_size += count;
 
 	return m_size;
 }
 
-/**
-	Clears the content of the array.
-@note
-	Does not free memory, it only zeroes
-	the number of items in the array.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline void List<T>::clear()
 {
 	m_size = 0;
 }
 
-/**
-	Copies the content of the other list into this.
-*/
+//-----------------------------------------------------------------------------
 template <typename T>
 inline const List<T>& List<T>::operator=(const List<T>& other)
 {
 	if (m_array)
 	{
-		m_allocator->deallocate(m_array);
+		m_allocator.deallocate(m_array);
 	}
 
 	m_size = other.m_size;
@@ -351,7 +332,7 @@ inline const List<T>& List<T>::operator=(const List<T>& other)
 
 	if (m_capacity)
 	{
-		m_array = (T*)m_allocator->allocate(m_capacity * sizeof(T));
+		m_array = (T*)m_allocator.allocate(m_capacity * sizeof(T));
 
 		memcpy(m_array, other.m_array, m_size * sizeof(T));
 	}

src/core/containers/Queue.h

@@ -34,9 +34,9 @@ OTHER DEALINGS IN THE SOFTWARE.
 namespace crown
 {
 
-/**
-	Circular buffer double-ended queue.
-*/
+/// Circular buffer double-ended queue of POD items.
+/// @note
+/// Does not call constructors/destructors so it is not very suitable for non-POD items.
 template <typename T>
 class Queue
 {
@@ -45,20 +45,51 @@ public:
 					Queue(Allocator& allocator);
 					~Queue();
 
+	/// Random access by index
 	T&				operator[](uint32_t index);
+
+	/// Random access by index
 	const T&		operator[](uint32_t index) const;
 
+	/// Returns whether the queue is empty.
 	bool			empty() const;
+
+	/// Returns the number of items in the queue
 	uint32_t		size() const;
+
+	/// Returns the number of items the queue can hold before
+	/// a resize must occur.
 	uint32_t		space() const;
+
+	/// Increase or decrease the capacity of the queue.
+	/// @note
+	/// Old items will be copied to the newly created queue.
+	/// If the new @capacity is smaller than the previous one, the
+	/// queue will be truncated.
 	void			increase_capacity(uint32_t capacity);
+
+	/// Grows the queue to contain at least @min_capacity items.
+	/// If @min_capacity is set to 0, the queue automatically
+	/// determines the new capacity based on its size at the 
+	/// time of call.
 	void			grow(uint32_t min_capacity);
 
+	/// Adds an @item to the back of the queue
 	void			push_back(const T& item);
+
+	/// Removes the last item from the queue
 	void			pop_back();
+
+	/// Adds an @item to the front of the queue
 	void			push_front(const T& item);
+
+	/// Removes the first item from the queue
 	void			pop_front();
 	
+	/// Clears the content of the queue.
+	/// @note
+	/// Does not free memory nor call destructors, it only zeroes
+	/// the number of items in the queue for efficiency.
 	void 			clear();
 
 	T*				begin();