[Bf-blender-cvs] [d4aeec9] master: BLI_stack: function comments

[Campbell Barton]

Commit: d4aeec9204e9c4a8e1d0980cca0eacd6c8c54eaf
Author: Campbell Barton
Date:   Fri Jun 19 15:54:42 2015 +1000
Branches: master
https://developer.blender.org/rBd4aeec9204e9c4a8e1d0980cca0eacd6c8c54eaf

BLI_stack: function comments

===================================================================

M	source/blender/blenlib/intern/stack.c

===================================================================

diff --git a/source/blender/blenlib/intern/stack.c b/source/blender/blenlib/intern/stack.c
index 3c9e1a5..36fad5a 100644
--- a/source/blender/blenlib/intern/stack.c
+++ b/source/blender/blenlib/intern/stack.c
@@ -125,8 +125,10 @@ void BLI_stack_free(BLI_Stack *stack)
 }
 
 /**
- * Copies the source value onto the stack (note that it copies
- * elem_size bytes from 'src', the pointer itself is not stored)
+ * Push a new item onto the stack.
+ *
+ * \return a pointer #BLI_Stack.elem_size
+ * bytes of uninitialized memory (caller must fill in).
  */
 void *BLI_stack_push_r(BLI_Stack *stack)
 {
@@ -158,6 +160,14 @@ void *BLI_stack_push_r(BLI_Stack *stack)
 	return CHUNK_LAST_ELEM(stack);
 }
 
+/**
+ * Copies the source value onto the stack
+ *
+ * \note This copies #BLI_Stack.elem_size bytes from \a src,
+ * (the pointer itself is not stored).
+ *
+ * \param src: source data to be copied to the stack.
+ */
 void BLI_stack_push(BLI_Stack *stack, const void *src)
 {
 	void *dst = BLI_stack_push_r(stack);
@@ -179,6 +189,15 @@ void BLI_stack_pop(BLI_Stack *stack, void *dst)
 	BLI_stack_discard(stack);
 }
 
+/**
+ * A version of #BLI_stack_pop which which fills in an array.
+ *
+ * \param dst: The destination array,
+ * must be at least (#BLI_Stack.elem_size * \a n) bytes long.
+ * \param n: The number of items to pop.
+ *
+ * \note The first item in the array will be last item added to the stack.
+ */
 void BLI_stack_pop_n(BLI_Stack *stack, void *dst, unsigned int n)
 {
 	BLI_assert(n <= BLI_stack_count(stack));
@@ -196,6 +215,9 @@ void *BLI_stack_peek(BLI_Stack *stack)
 	return CHUNK_LAST_ELEM(stack);
 }
 
+/**
+ * Removes the top element from the stack.
+ */
 void BLI_stack_discard(BLI_Stack *stack)
 {
 	BLI_assert(BLI_stack_is_empty(stack) == false);