Docs: comment functions in BLI & Py API

8 files changed, 71 insertions, 28 deletions

diff --git a/release/scripts/modules/bpy/path.py b/release/scripts/modules/bpy/path.py
index d5b64933165..b7d7d9ee694 100644
--- a/release/scripts/modules/bpy/path.py
+++ b/release/scripts/modules/bpy/path.py
@@ -61,7 +61,7 @@ def abspath(path, start=None, library=None):
 
     :arg start: Relative to this path,
        when not set the current filename is used.
-    :type start: string
+    :type start: string or bytes
     :arg library: The library this path is from. This is only included for
        convenience, when the library is not None its path replaces *start*.
     :type library: :class:`bpy.types.Library`
@@ -90,9 +90,11 @@ def relpath(path, start=None):
     """
     Returns the path relative to the current blend file using the "//" prefix.
 
+    :arg path: An absolute path.
+    :type path: string or bytes
     :arg start: Relative to this path,
        when not set the current filename is used.
-    :type start: string
+    :type start: string or bytes
     """
     if isinstance(path, bytes):
         if not path.startswith(b"//"):
@@ -112,6 +114,9 @@ def is_subdir(path, directory):
     """
     Returns true if *path* in a subdirectory of *directory*.
     Both paths must be absolute.
+
+    :arg path: An absolute path.
+    :type path: string or bytes
     """
     from os.path import normpath, normcase
     path = normpath(normcase(path))
@@ -129,7 +134,7 @@ def clean_name(name, replace="_"):
     may cause problems under various circumstances,
     such as writing to a file.
     All characters besides A-Z/a-z, 0-9 are replaced with "_"
-    or the replace argument if defined.
+    or the *replace* argument if defined.
     """
 
     if replace != "_":
diff --git a/source/blender/blenlib/BLI_memarena.h b/source/blender/blenlib/BLI_memarena.h
index 8d5a7654425..6b1d32b48f2 100644
--- a/source/blender/blenlib/BLI_memarena.h
+++ b/source/blender/blenlib/BLI_memarena.h
@@ -27,11 +27,6 @@
 
 /** \file BLI_memarena.h
  *  \ingroup bli
- *  \brief Memory arena ADT.
- *  \section aboutmemarena Memory Arena
- * Memory arena's are commonly used when the program
- * needs to quickly allocate lots of little bits of
- * data, which are all freed at the same moment.
  */
 
 #ifndef __BLI_MEMARENA_H__
diff --git a/source/blender/blenlib/BLI_mempool.h b/source/blender/blenlib/BLI_mempool.h
index 64e673f6db2..37d1fb4647d 100644
--- a/source/blender/blenlib/BLI_mempool.h
+++ b/source/blender/blenlib/BLI_mempool.h
@@ -30,8 +30,6 @@
 
 /** \file BLI_mempool.h
  *  \ingroup bli
- *  \author Geoffrey Bantle
- *  \brief Simple fast memory allocator for fixed size chunks.
  */
 
 #ifdef __cplusplus
@@ -46,10 +44,6 @@ struct BLI_mempool_chunk;
 
 typedef struct BLI_mempool BLI_mempool;
 
-/* allow_iter allows iteration on this mempool.  note: this requires that the
- * first four bytes of the elements never contain the character string
- * 'free'.  use with care.*/
-
 BLI_mempool *BLI_mempool_create(unsigned int esize, unsigned int totelem,
                                 unsigned int pchunk, unsigned int flag) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
 void        *BLI_mempool_alloc(BLI_mempool *pool) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
@@ -82,6 +76,11 @@ typedef struct BLI_mempool_iter {
 /* flag */
 enum {
 	BLI_MEMPOOL_NOP = 0,
+	/** allow iterating on this mempool.
+	 *
+	 * \note this requires that the first four bytes of the elements never begin with 'free'
+ 	 * \note order of iteration is only assured to be the order of allocation when no chunks have been freed.
+	 */
 	BLI_MEMPOOL_ALLOW_ITER = (1 << 0),
 };
 
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>
diff --git a/source/blender/blenlib/intern/BLI_kdopbvh.c b/source/blender/blenlib/intern/BLI_kdopbvh.c
index e4504bcaab1..6eab670b359 100644
--- a/source/blender/blenlib/intern/BLI_kdopbvh.c
+++ b/source/blender/blenlib/intern/BLI_kdopbvh.c
@@ -27,6 +27,16 @@
 
 /** \file blender/blenlib/intern/BLI_kdopbvh.c
  *  \ingroup bli
+ *  \brief BVH-tree implementation.
+ *
+ * KD-Overlap-BVH, implements a bvh-tree structure with support for:
+ *
+ * - Ray-cast:
+ *   #BLI_bvhtree_ray_cast, #BVHRayCastData
+ * - Nearest point on surface:
+ *   #BLI_bvhtree_find_nearest, #BVHNearestData
+ * - Overlapping 2 trees:
+ *   #BLI_bvhtree_overlap, #BVHOverlapData
  */
 
 #include <assert.h>
diff --git a/source/blender/blenlib/intern/BLI_memarena.c b/source/blender/blenlib/intern/BLI_memarena.c
index dd0997c8e1c..2604dbafdc0 100644
--- a/source/blender/blenlib/intern/BLI_memarena.c
+++ b/source/blender/blenlib/intern/BLI_memarena.c
@@ -28,6 +28,14 @@
 
 /** \file blender/blenlib/intern/BLI_memarena.c
  *  \ingroup bli
+ *  \brief Memory arena ADT.
+ *  \section aboutmemarena Memory Arena
+ *
+ * Memory arena's are commonly used when the program
+ * needs to quickly allocate lots of little bits of data,
+ * which are all freed at the same moment.
+ *
+ * \note Memory can't be freed during the arenas lifetime.
  */
 
 #include <stdlib.h>
diff --git a/source/blender/blenlib/intern/BLI_mempool.c b/source/blender/blenlib/intern/BLI_mempool.c
index 8fc5f97221d..7338804c685 100644
--- a/source/blender/blenlib/intern/BLI_mempool.c
+++ b/source/blender/blenlib/intern/BLI_mempool.c
@@ -27,8 +27,15 @@
 
 /** \file blender/blenlib/intern/BLI_mempool.c
  *  \ingroup bli
+ *  \author Geoffrey Bantle
  *
  * Simple, fast memory allocator for allocating many elements of the same size.
+ *
+ * Supports:
+ *
+ * - Freeing chunks.
+ * - Iterating over allocated chunks
+ *   (optionally when using the #BLI_MEMPOOL_ALLOW_ITER flag).
  */
 
 #include <string.h>
diff --git a/source/blender/blenlib/intern/array_utils.c b/source/blender/blenlib/intern/array_utils.c
index 6c5dc5a7f1e..65c653c9b4f 100644
--- a/source/blender/blenlib/intern/array_utils.c
+++ b/source/blender/blenlib/intern/array_utils.c
@@ -21,6 +21,10 @@
 /** \file blender/blenlib/intern/array_utils.c
  *  \ingroup bli
  *  \brief Generic array manipulation API.
+ *
+ * \warning Some array operations here are inherently inefficient,
+ * and only included for the cases where the performance is acceptable.
+ * Use with care.
  */
 #include <string.h>
 #include <stdlib.h>
@@ -35,7 +39,11 @@
 
 #include "BLI_strict_flags.h"
 
-
+/**
+ *In-place array reverse.
+ *
+ * Access via #BLI_array_reverse
+ */
 void _bli_array_reverse(void *arr_v, unsigned int arr_len, size_t arr_stride)
 {
 	const unsigned int arr_stride_uint = (unsigned int)arr_stride;
@@ -54,6 +62,12 @@ void _bli_array_reverse(void *arr_v, unsigned int arr_len, size_t arr_stride)
 	}
 }
 
+/**
+ * In-place array wrap.
+ * (rotate the array one step forward or backwards).
+ *
+ * Access via #BLI_array_wrap
+ */
 void _bli_array_wrap(void *arr_v, unsigned int arr_len, size_t arr_stride, int dir)
 {
 	char *arr = arr_v;
@@ -74,6 +88,12 @@ void _bli_array_wrap(void *arr_v, unsigned int arr_len, size_t arr_stride, int d
 	}
 }
 
+/**
+ *In-place array permute.
+ * (re-arrange elemrnts based on an array of indices).
+ *
+ * Access via #BLI_array_wrap
+ */
 void _bli_array_permute(
         void *arr_v, const unsigned int arr_len, const size_t arr_stride,
         const unsigned int *order, void *arr_temp)
@@ -105,6 +125,10 @@ void _bli_array_permute(
 }
 
 /**
+ * Find the first index of an item in an array.
+ *
+ * Access via #BLI_array_findindex
+ *
  * \note Not efficient, use for error checks/asserts.
  */
 int _bli_array_findindex(const void *arr, unsigned int arr_len, size_t arr_stride, const void *p)