From 249f4423ee1c28e7f8ad6fdfff6c61a1f3e6d53d Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Mon, 25 Nov 2019 01:14:39 +1100 Subject: Cleanup: doxygen comments Also correct some outdated symbol references, add missing 'name' commands. --- source/blender/blenlib/BLI_array.h | 3 ++- source/blender/blenlib/BLI_rand.h | 6 +++--- source/blender/blenlib/BLI_voxel.h | 2 +- source/blender/blenlib/intern/delaunay_2d.c | 9 ++++++--- source/blender/blenlib/intern/hash_md5.c | 10 ++++++---- source/blender/blenlib/intern/kdtree_impl.h | 6 ++++-- source/blender/blenlib/intern/math_base_inline.c | 12 ++++++++---- source/blender/blenlib/intern/math_geom.c | 9 +++++---- source/blender/blenlib/intern/math_matrix.c | 6 ++++-- source/blender/blenlib/intern/math_rotation.c | 4 ++-- source/blender/blenlib/intern/path_util.c | 12 ++++++++---- 11 files changed, 49 insertions(+), 30 deletions(-) (limited to 'source/blender/blenlib') diff --git a/source/blender/blenlib/BLI_array.h b/source/blender/blenlib/BLI_array.h index 57e1790fdfd..5b85711f8ac 100644 --- a/source/blender/blenlib/BLI_array.h +++ b/source/blender/blenlib/BLI_array.h @@ -42,7 +42,8 @@ /** \} */ -/** BLI_array.c +/** + * BLI_array.c * * Doing the realloc in a macro isn't so simple, * so use a function the macros can use. diff --git a/source/blender/blenlib/BLI_rand.h b/source/blender/blenlib/BLI_rand.h index eec4e885493..be2b18b05fd 100644 --- a/source/blender/blenlib/BLI_rand.h +++ b/source/blender/blenlib/BLI_rand.h @@ -72,9 +72,9 @@ void BLI_array_frand(float *ar, int count, unsigned int seed); /** Return a pseudo-random (hash) float from an integer value */ float BLI_hash_frand(unsigned int seed) ATTR_WARN_UNUSED_RESULT; -/** Shuffle an array randomly using the given seed. - * contents. This routine does not use nor modify - * the state of the BLI random number generator. +/** + * Shuffle an array randomly using the given seed contents. + * This routine does not use nor modify the state of the BLI random number generator. */ void BLI_array_randomize(void *data, unsigned int elem_size, diff --git a/source/blender/blenlib/BLI_voxel.h b/source/blender/blenlib/BLI_voxel.h index 2a02eb380b5..ef210a82a65 100644 --- a/source/blender/blenlib/BLI_voxel.h +++ b/source/blender/blenlib/BLI_voxel.h @@ -24,7 +24,7 @@ * \ingroup bli */ -/** find the index number of a voxel, given x/y/z integer coords and resolution vector */ +/** Find the index number of a voxel, given x/y/z integer coords and resolution vector. */ #define BLI_VOXEL_INDEX(x, y, z, res) \ ((int64_t)(x) + (int64_t)(y) * (int64_t)(res)[0] + \ diff --git a/source/blender/blenlib/intern/delaunay_2d.c b/source/blender/blenlib/intern/delaunay_2d.c index 9c1e52b53a4..27f7a2a4430 100644 --- a/source/blender/blenlib/intern/delaunay_2d.c +++ b/source/blender/blenlib/intern/delaunay_2d.c @@ -115,8 +115,10 @@ static void validate_face_centroid(SymEdge *se); static void validate_cdt(CDT_state *cdt, bool check_all_tris); #endif -/** return 1 if a,b,c forms CCW angle, -1 if a CW angle, 0 if straight. - * For straight test, allow b to be withing eps of line. */ +/** + * Return 1 if a,b,c forms CCW angle, -1 if a CW angle, 0 if straight. + * For straight test, allow b to be withing eps of line. + */ static int CCW_test(const double a[2], const double b[2], const double c[2], const double eps) { double det; @@ -902,7 +904,8 @@ static LocateResult locate_point(CDT_state *cdt, const double p[2]) return lr; } -/** Return true if circumcircle(v1, v2, v3) does not contain p. +/** + * Return true if circumcircle(v1, v2, v3) does not contain p. * To avoid possible infinite flip loops, we will say true even if p is inside the circle * but less than epsilon from the boundary; or if v1, v2, v3, form a straight line. */ diff --git a/source/blender/blenlib/intern/hash_md5.c b/source/blender/blenlib/intern/hash_md5.c index f9e9b3bfbf9..5ec1c91a735 100644 --- a/source/blender/blenlib/intern/hash_md5.c +++ b/source/blender/blenlib/intern/hash_md5.c @@ -94,8 +94,9 @@ struct md5_ctx { * (RFC 1321, 3.1: Step 1) */ static const unsigned char fillbuf[64] = {0x80, 0 /* , 0, 0, ... */}; -/** Initialize structure containing state of computation. - * (RFC 1321, 3.3: Step 3) +/** + * Initialize structure containing state of computation. + * (RFC 1321, 3.3: Step 3) */ static void md5_init_ctx(struct md5_ctx *ctx) { @@ -283,8 +284,9 @@ static void *md5_read_ctx(const struct md5_ctx *ctx, void *resbuf) /* Top level public functions. */ -/** Compute MD5 message digest for bytes read from 'stream'. - * The resulting message digest number will be written into the 16 bytes beginning at 'resblock'. +/** + * Compute MD5 message digest for bytes read from 'stream'. + * The resulting message digest number will be written into the 16 bytes beginning at 'resblock'. * \return Non-zero if an error occurred. */ int BLI_hash_md5_stream(FILE *stream, void *resblock) diff --git a/source/blender/blenlib/intern/kdtree_impl.h b/source/blender/blenlib/intern/kdtree_impl.h index 32e8a4e90f5..404e136a0a6 100644 --- a/source/blender/blenlib/intern/kdtree_impl.h +++ b/source/blender/blenlib/intern/kdtree_impl.h @@ -58,8 +58,10 @@ struct KDTree { #define KD_NODE_UNSET ((uint)-1) -/** When set we know all values are unbalanced, - * otherwise clear them when re-balancing: see T62210. */ +/** + * When set we know all values are unbalanced, + * otherwise clear them when re-balancing: see T62210. + */ #define KD_NODE_ROOT_IS_INIT ((uint)-2) /* -------------------------------------------------------------------- */ diff --git a/source/blender/blenlib/intern/math_base_inline.c b/source/blender/blenlib/intern/math_base_inline.c index 0309876d8fb..4c86b9d3396 100644 --- a/source/blender/blenlib/intern/math_base_inline.c +++ b/source/blender/blenlib/intern/math_base_inline.c @@ -526,15 +526,19 @@ MINLINE int signum_i(float a) } } -/** Returns number of (base ten) *significant* digits of integer part of given float - * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). */ +/** + * Returns number of (base ten) *significant* digits of integer part of given float + * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). + */ MINLINE int integer_digits_f(const float f) { return (f == 0.0f) ? 0 : (int)floor(log10(fabs(f))) + 1; } -/** Returns number of (base ten) *significant* digits of integer part of given double - * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). */ +/** + * Returns number of (base ten) *significant* digits of integer part of given double + * (negative in case of decimal-only floats, 0.01 returns -1 e.g.). + */ MINLINE int integer_digits_d(const double d) { return (d == 0.0) ? 0 : (int)floor(log10(fabs(d))) + 1; diff --git a/source/blender/blenlib/intern/math_geom.c b/source/blender/blenlib/intern/math_geom.c index 67ef4d57b4b..27715ed49b5 100644 --- a/source/blender/blenlib/intern/math_geom.c +++ b/source/blender/blenlib/intern/math_geom.c @@ -2996,8 +2996,9 @@ int isect_line_line_v3(const float v1[3], return isect_line_line_epsilon_v3(v1, v2, v3, v4, r_i1, r_i2, epsilon); } -/** Intersection point strictly between the two lines - * \return false when no intersection is found +/** + * Intersection point strictly between the two lines + * \return false when no intersection is found. */ bool isect_line_line_strict_v3(const float v1[3], const float v2[3], @@ -3188,7 +3189,7 @@ bool isect_ray_aabb_v3(const struct IsectRayAABB_Precalc *data, * Test a bounding box (AABB) for ray intersection. * Assumes the ray is already local to the boundbox space. * - * \note: \a direction should be normalized + * \note \a direction should be normalized * if you intend to use the \a tmin or \a tmax distance results! */ bool isect_ray_aabb_v3_simple(const float orig[3], @@ -3791,7 +3792,7 @@ bool barycentric_coords_v2( } /** - * \note: using #cross_tri_v2 means locations outside the triangle are correctly weighted + * \note Using #cross_tri_v2 means locations outside the triangle are correctly weighted. * * \note This is *exactly* the same calculation as #resolve_tri_uv_v2, * although it has double precision and is used for texture baking, so keep both. diff --git a/source/blender/blenlib/intern/math_matrix.c b/source/blender/blenlib/intern/math_matrix.c index 48884082dd8..5118d8a698e 100644 --- a/source/blender/blenlib/intern/math_matrix.c +++ b/source/blender/blenlib/intern/math_matrix.c @@ -1964,8 +1964,10 @@ void mat4_to_size(float size[3], const float mat[4][4]) size[2] = len_v3(mat[2]); } -/** Extract scale factors from the matrix, with correction to ensure - * exact volume in case of a sheared matrix. */ +/** + * Extract scale factors from the matrix, with correction to ensure + * exact volume in case of a sheared matrix. + */ void mat4_to_size_fix_shear(float size[3], const float mat[4][4]) { mat4_to_size(size, mat); diff --git a/source/blender/blenlib/intern/math_rotation.c b/source/blender/blenlib/intern/math_rotation.c index 37c0c05b061..94f0f523c6e 100644 --- a/source/blender/blenlib/intern/math_rotation.c +++ b/source/blender/blenlib/intern/math_rotation.c @@ -77,7 +77,7 @@ void mul_qt_qtqt(float q[4], const float q1[4], const float q2[4]) } /** - * \note: + * \note * Assumes a unit quaternion? * * in fact not, but you may want to use a unit quat, read on... @@ -93,7 +93,7 @@ void mul_qt_qtqt(float q[4], const float q1[4], const float q2[4]) * For people used to python mathutils, its like: * def mul_qt_v3(q, v): (q * Quaternion((0.0, v[0], v[1], v[2])) * q.conjugated())[1:] * - * \note: multiplying by 3x3 matrix is ~25% faster. + * \note Multiplying by 3x3 matrix is ~25% faster. */ void mul_qt_v3(const float q[4], float v[3]) { diff --git a/source/blender/blenlib/intern/path_util.c b/source/blender/blenlib/intern/path_util.c index 725b6f8937a..dff1f77c1ab 100644 --- a/source/blender/blenlib/intern/path_util.c +++ b/source/blender/blenlib/intern/path_util.c @@ -57,8 +57,10 @@ #ifdef WIN32 -/** Return true if the path is absolute ie starts with a drive specifier - * (eg A:\) or is a UNC path. */ +/** + * Return true if the path is absolute ie starts with a drive specifier + * (eg A:\) or is a UNC path. + */ static bool BLI_path_is_abs(const char *name); #endif /* WIN32 */ @@ -444,8 +446,10 @@ static int BLI_path_unc_prefix_len(const char *path) #if defined(WIN32) -/** Return true if the path is absolute ie starts with a drive specifier - * (eg A:\) or is a UNC path. */ +/** + * Return true if the path is absolute ie starts with a drive specifier + * (eg A:\) or is a UNC path. + */ static bool BLI_path_is_abs(const char *name) { return (name[1] == ':' && (name[2] == '\\' || name[2] == '/')) || BLI_path_is_unc(name); -- cgit v1.2.3