From 62c8f46ab6f16f99bcf848936a690e01f4c9e770 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 5 Aug 2015 00:21:50 +1000 Subject: Docs: comment functions in BLI & Py API --- release/scripts/modules/bpy/path.py | 11 ++++++++--- source/blender/blenlib/BLI_memarena.h | 5 ----- source/blender/blenlib/BLI_mempool.h | 11 +++++------ source/blender/blenlib/intern/BLI_array.c | 21 ++++++++------------- source/blender/blenlib/intern/BLI_kdopbvh.c | 10 ++++++++++ source/blender/blenlib/intern/BLI_memarena.c | 8 ++++++++ source/blender/blenlib/intern/BLI_mempool.c | 7 +++++++ source/blender/blenlib/intern/array_utils.c | 26 +++++++++++++++++++++++++- 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 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 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 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 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 #include @@ -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) -- cgit v1.2.3