[Bf-blender-cvs] [62c8f46] master: Docs: comment functions in BLI & Py API
Campbell Barton
noreply at git.blender.org
Tue Aug 4 09:12:27 CEST 2015
Commit: 62c8f46ab6f16f99bcf848936a690e01f4c9e770
Author: Campbell Barton
Date: Wed Aug 5 00:21:50 2015 +1000
Branches: master
https://developer.blender.org/rB62c8f46ab6f16f99bcf848936a690e01f4c9e770
Docs: comment functions in BLI & Py API
===================================================================
M release/scripts/modules/bpy/path.py
M source/blender/blenlib/BLI_memarena.h
M source/blender/blenlib/BLI_mempool.h
M source/blender/blenlib/intern/BLI_array.c
M source/blender/blenlib/intern/BLI_kdopbvh.c
M source/blender/blenlib/intern/BLI_memarena.c
M source/blender/blenlib/intern/BLI_mempool.c
M source/blender/blenlib/intern/array_utils.c
===================================================================
diff --git a/release/scripts/modules/bpy/path.py b/release/scripts/modules/bpy/path.py
index d5b6493..b7d7d9e 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 8d5a765..6b1d32b 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 64e673f..37d1fb4 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 01550ad..f681d22 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 e4504bc..6eab670 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 dd0997c..2604dba 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 8fc5f97..7338804 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 6c5dc5a..65c653c 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)
More information about the Bf-blender-cvs
mailing list