Docs: comment functions in BLI & Py API

1 files changed, 8 insertions, 13 deletions

diff --git a/source/blender/blenlib/intern/BLI_array.c b/source/blender/blenlib/intern/BLI_array.c
index 01550ad1008..f681d222e69 100644
--- a/source/blender/blenlib/intern/BLI_array.c
+++ b/source/blender/blenlib/intern/BLI_array.c
@@ -30,18 +30,12 @@
  *  \ingroup bli
  *  \brief A (mainly) macro array library.
  *
- * This library needs to be changed to not use macros quite so heavily,
- * and to be more of a complete array API.  The way arrays are
- * exposed to client code as normal C arrays is very useful though, imho.
- * it does require some use of macros, however.
+ * This is an array library, used to manage array (re)allocation.
  *
- * anyway, it's used a bit too heavily to simply rewrite as a
- * more "correct" solution without macros entirely.  I originally wrote this
- * to be very easy to use, without the normal pain of most array libraries.
- * This was especially helpful when it came to the massive refactors necessary
- * for bmesh, and really helped to speed the process up. - joeedh
+ * \note This is primarily accessed via macros,
+ * functions are used to implement some of the internals.
  *
- * little array macro library.  example of usage:
+ * Example usage:
  *
  * \code{.c}
  * int *arr = NULL;
@@ -55,9 +49,10 @@
  * BLI_array_free(arr);
  * \endcode
  *
- * arrays are buffered, using double-buffering (so on each reallocation,
- * the array size is doubled).  supposedly this should give good Big Oh
- * behavior, though it may not be the best in practice.
+ * Arrays are over allocated, so each reallocation the array size is doubled.
+ * In situations where contiguous array access isn't needed,
+ * other solutions for allocation are available.
+ * Consider using on of: BLI_memarena.c, BLI_mempool.c, BLi_stack.c
  */
 
 #include <string.h>