[FFmpeg-cvslog] lavu/mem: extend documentation for av_dynarray_add()

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Thu Apr 25 00:06:13 2013 +0200| [c773adee3fda94e943ead1292330d25b28e10deb] | committer: Stefano Sabatini

lavu/mem: extend documentation for av_dynarray_add()

In particular, mention the fact that the amortized element addition cost
is constant.

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=c773adee3fda94e943ead1292330d25b28e10deb
---

 libavutil/mem.h |   17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/libavutil/mem.h b/libavutil/mem.h
index 02395b7..861029a 100644
--- a/libavutil/mem.h
+++ b/libavutil/mem.h
@@ -199,9 +199,20 @@ void av_freep(void *ptr);
 /**
  * Add an element to a dynamic array.
  *
- * @param tab_ptr Pointer to the array.
- * @param nb_ptr  Pointer to the number of elements in the array.
- * @param elem    Element to be added.
+ * The array to grow is supposed to be an array of pointers to
+ * structures, and the element to add must be a pointer to an already
+ * allocated structure.
+ *
+ * The array is reallocated when its sizes reaches powers of 2.
+ * Therefore, the amortized cost of adding an element is constant.
+ *
+ * In case of success, the pointer to the array is updated in order to
+ * point to the new grown array, and the number pointed to by nb_ptr
+ * is incremented.
+ *
+ * @param tab_ptr pointer to the array to grow
+ * @param nb_ptr  pointer to the number of elements in the array
+ * @param elem    element to add
  */
 void av_dynarray_add(void *tab_ptr, int *nb_ptr, void *elem);