lavu/mem: extend documentation for av_dynarray_add()

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

1 files changed, 14 insertions, 3 deletions

diff --git a/libavutil/mem.h b/libavutil/mem.h
index 02395b792b..861029a2f2 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);