From eff8cc9cccdaa7248d9d869473704e9db69c2f41 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sun, 14 Apr 2019 10:48:42 +0200 Subject: Cleanup: doxy comments Use doxy references to function and enums, also correct some names which became out of sync. --- source/blender/blenkernel/BKE_blender_version.h | 20 ++++++++++++-------- source/blender/blenkernel/intern/armature.c | 16 +++++++++++----- source/blender/blenkernel/intern/collection.c | 2 +- source/blender/blenkernel/intern/constraint.c | 9 ++++++--- source/blender/blenkernel/intern/crazyspace.c | 7 ++++--- source/blender/blenkernel/intern/image.c | 10 ++++++---- source/blender/blenkernel/intern/library_query.c | 2 +- source/blender/blenkernel/intern/mesh_validate.c | 11 +++++++---- source/blender/blenkernel/intern/object.c | 14 ++++++++------ source/blender/blenkernel/intern/object_update.c | 8 +++++--- source/blender/blenkernel/intern/pbvh.c | 2 +- source/blender/blenkernel/intern/softbody.c | 5 +++-- .../blender/blenkernel/intern/tracking_stabilize.c | 13 +++++++------ 13 files changed, 72 insertions(+), 47 deletions(-) (limited to 'source/blender/blenkernel') diff --git a/source/blender/blenkernel/BKE_blender_version.h b/source/blender/blenkernel/BKE_blender_version.h index 9c47cc9f22b..1b56e203947 100644 --- a/source/blender/blenkernel/BKE_blender_version.h +++ b/source/blender/blenkernel/BKE_blender_version.h @@ -20,21 +20,25 @@ * \ingroup bke */ -/* these lines are grep'd, watch out for our not-so-awesome regex - * and keep comment above the defines. - * Use STRINGIFY() rather than defining with quotes */ +/** + * The lines below use regex from scripts to extract their values, + * Keep this in mind when modifying this file and keep this comment above the defines. + * + * \note Use #STRINGIFY() rather than defining with quotes. + */ #define BLENDER_VERSION 280 #define BLENDER_SUBVERSION 55 -/* Several breakages with 280, e.g. collections vs layers */ +/** Several breakages with 280, e.g. collections vs layers. */ #define BLENDER_MINVERSION 280 #define BLENDER_MINSUBVERSION 0 -/* used by packaging tools */ -/* can be left blank, otherwise a,b,c... etc with no quotes */ +/** Used by packaging tools. */ +/** Can be left blank, otherwise a,b,c... etc with no quotes. */ #define BLENDER_VERSION_CHAR -/* alpha/beta/rc/release, docs use this */ +/** alpha/beta/rc/release, docs use this. */ #define BLENDER_VERSION_CYCLE beta -extern char versionstr[]; /* from blender.c */ +/** Defined in from blender.c */ +extern char versionstr[]; #endif /* __BKE_BLENDER_VERSION_H__ */ diff --git a/source/blender/blenkernel/intern/armature.c b/source/blender/blenkernel/intern/armature.c index 5123b159440..890a62351c1 100644 --- a/source/blender/blenkernel/intern/armature.c +++ b/source/blender/blenkernel/intern/armature.c @@ -1714,7 +1714,9 @@ void BKE_armature_mat_pose_to_bone_ex(struct Depsgraph *depsgraph, Object *ob, b BKE_armature_mat_pose_to_bone(&work_pchan, inmat, outmat); } -/* same as BKE_object_mat3_to_rot() */ +/** + * Same as #BKE_object_mat3_to_rot(). + */ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, float mat[3][3], bool use_compat) { BLI_ASSERT_UNIT_M3(mat); @@ -1735,8 +1737,10 @@ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, float mat[3][3], bool use_compat } } -/* Apply a 4x4 matrix to the pose bone, - * similar to BKE_object_apply_mat4() */ +/** + * Apply a 4x4 matrix to the pose bone, + * similar to #BKE_object_apply_mat4(). + */ void BKE_pchan_apply_mat4(bPoseChannel *pchan, float mat[4][4], bool use_compat) { float rot[3][3]; @@ -1744,9 +1748,11 @@ void BKE_pchan_apply_mat4(bPoseChannel *pchan, float mat[4][4], bool use_compat) BKE_pchan_mat3_to_rot(pchan, rot, use_compat); } -/* Remove rest-position effects from pose-transform for obtaining +/** + * Remove rest-position effects from pose-transform for obtaining * 'visual' transformation of pose-channel. - * (used by the Visual-Keyframing stuff) */ + * (used by the Visual-Keyframing stuff). + */ void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], float pose_mat[4][4], float arm_mat[4][4]) { float imat[4][4]; diff --git a/source/blender/blenkernel/intern/collection.c b/source/blender/blenkernel/intern/collection.c index 336a4739760..eadf190c363 100644 --- a/source/blender/blenkernel/intern/collection.c +++ b/source/blender/blenkernel/intern/collection.c @@ -804,7 +804,7 @@ static void collection_missing_parents_remove(Collection *collection) * This is used for library remapping, where these pointers have been set to NULL. * Otherwise this should never happen. * - * \note caller must ensure BKE_main_collection_sync_remap() is called afterwards! + * \note caller must ensure #BKE_main_collection_sync_remap() is called afterwards! * * \param collection: may be \a NULL, in which case whole \a bmain database of collections is checked. */ diff --git a/source/blender/blenkernel/intern/constraint.c b/source/blender/blenkernel/intern/constraint.c index 7d9a6c234a0..e8a4983528e 100644 --- a/source/blender/blenkernel/intern/constraint.c +++ b/source/blender/blenkernel/intern/constraint.c @@ -4709,15 +4709,18 @@ const bConstraintTypeInfo *BKE_constraint_typeinfo_get(bConstraint *con) /* ---------- Data Management ------- */ -/* helper function for BKE_constraint_free_data() - unlinks references */ +/** + * Helper function for #BKE_constraint_free_data() - unlinks references. + */ static void con_unlink_refs_cb(bConstraint *UNUSED(con), ID **idpoin, bool is_reference, void *UNUSED(userData)) { if (*idpoin && is_reference) id_us_min(*idpoin); } -/* Free data of a specific constraint if it has any info. - * be sure to run BIK_clear_data() when freeing an IK constraint, +/** + * Free data of a specific constraint if it has any info. + * be sure to run #BIK_clear_data() when freeing an IK constraint, * unless DAG_relations_tag_update is called. */ void BKE_constraint_free_data_ex(bConstraint *con, bool do_id_user) diff --git a/source/blender/blenkernel/intern/crazyspace.c b/source/blender/blenkernel/intern/crazyspace.c index 5dd5e014cc8..4aa3b702693 100644 --- a/source/blender/blenkernel/intern/crazyspace.c +++ b/source/blender/blenkernel/intern/crazyspace.c @@ -305,12 +305,13 @@ int BKE_crazyspace_get_first_deform_matrices_editbmesh( return numleft; } -/* Crazyspace evaluation needs to have an object which has all the fields +/** + * Crazyspace evaluation needs to have an object which has all the fields * evaluated, but the mesh data being at undeformed state. This way it can * re-apply modifiers and also have proper pointers to key data blocks. * - * Similar to BKE_object_eval_reset(), but does not modify the actual evaluated - * object. */ + * Similar to #BKE_object_eval_reset(), but does not modify the actual evaluated object. + */ static void crazyspace_init_object_for_eval( struct Depsgraph *depsgraph, Object *object, diff --git a/source/blender/blenkernel/intern/image.c b/source/blender/blenkernel/intern/image.c index b00e4cbcdd9..0205f275f59 100644 --- a/source/blender/blenkernel/intern/image.c +++ b/source/blender/blenkernel/intern/image.c @@ -4770,8 +4770,9 @@ bool BKE_image_has_loaded_ibuf(Image *image) return has_loaded_ibuf; } -/* References the result, BKE_image_release_ibuf is to be called to de-reference. - * Use lock=NULL when calling BKE_image_release_ibuf(). +/** + * References the result, #BKE_image_release_ibuf is to be called to de-reference. + * Use lock=NULL when calling #BKE_image_release_ibuf(). */ ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name) { @@ -4797,8 +4798,9 @@ ImBuf *BKE_image_get_ibuf_with_name(Image *image, const char *name) return ibuf; } -/* References the result, BKE_image_release_ibuf is to be called to de-reference. - * Use lock=NULL when calling BKE_image_release_ibuf(). +/** + * References the result, #BKE_image_release_ibuf is to be called to de-reference. + * Use lock=NULL when calling #BKE_image_release_ibuf(). * * TODO(sergey): This is actually "get first entry from the cache", which is * not so much predictable. But using first loaded image buffer diff --git a/source/blender/blenkernel/intern/library_query.c b/source/blender/blenkernel/intern/library_query.c index 4fc1ea6bb62..b7ae8eea18d 100644 --- a/source/blender/blenkernel/intern/library_query.c +++ b/source/blender/blenkernel/intern/library_query.c @@ -1294,7 +1294,7 @@ bool BKE_library_ID_is_indirectly_used(Main *bmain, void *idv) } /** - * Combine \a BKE_library_ID_is_locally_used() and \a BKE_library_ID_is_indirectly_used() in a single call. + * Combine #BKE_library_ID_is_locally_used() and #BKE_library_ID_is_indirectly_used() in a single call. */ void BKE_library_ID_test_usages(Main *bmain, void *idv, bool *is_used_local, bool *is_used_linked) { diff --git a/source/blender/blenkernel/intern/mesh_validate.c b/source/blender/blenkernel/intern/mesh_validate.c index a5aa198bc4e..295b65190a8 100644 --- a/source/blender/blenkernel/intern/mesh_validate.c +++ b/source/blender/blenkernel/intern/mesh_validate.c @@ -1063,10 +1063,13 @@ void BKE_mesh_strip_loose_faces(Mesh *me) } } -/* Works on both loops and polys! */ -/* Note: It won't try to guess which loops of an invalid poly to remove! - * this is the work of the caller, to mark those loops... - * See e.g. BKE_mesh_validate_arrays(). */ +/** + * Works on both loops and polys! + * + * \note It won't try to guess which loops of an invalid poly to remove! + * this is the work of the caller, to mark those loops... + * See e.g. #BKE_mesh_validate_arrays(). + */ void BKE_mesh_strip_loose_polysloops(Mesh *me) { MPoly *p; diff --git a/source/blender/blenkernel/intern/object.c b/source/blender/blenkernel/intern/object.c index 9985c8026e7..6e9c8ecb480 100644 --- a/source/blender/blenkernel/intern/object.c +++ b/source/blender/blenkernel/intern/object.c @@ -1429,11 +1429,11 @@ Object *BKE_object_copy(Main *bmain, const Object *ob) /** Perform deep-copy of object and its 'children' data-blocks (obdata, materials, actions, etc.). * - * \param dupflag Controls which sub-data are also duplicated (see \a eDupli_ID_Flags in \a DNA_userdef_types.h). + * \param dupflag Controls which sub-data are also duplicated (see #eDupli_ID_Flags in DNA_userdef_types.h). * - * \note This function does not do any remapping to new IDs, caller must do it (\a BKE_libblock_relink_to_newid()). - * \note Caller MUST free \a newid pointers itself (\a BKE_main_id_clear_newpoins()) and call updates of DEG too - * (\a DAG_relations_tag_update()). + * \note This function does not do any remapping to new IDs, caller must do it (\a #BKE_libblock_relink_to_newid()). + * \note Caller MUST free \a newid pointers itself (#BKE_main_id_clear_newpoins()) and call updates of DEG too + * (#DAG_relations_tag_update()). */ Object *BKE_object_duplicate(Main *bmain, const Object *ob, const int dupflag) { @@ -3147,10 +3147,12 @@ void BKE_object_handle_update_ex(Depsgraph *depsgraph, object_handle_update_proxy(depsgraph, scene, ob, do_proxy_update); } -/* WARNING: "scene" here may not be the scene object actually resides in. +/** + * \warning "scene" here may not be the scene object actually resides in. * When dealing with background-sets, "scene" is actually the active scene. * e.g. "scene" <-- set 1 <-- set 2 ("ob" lives here) <-- set 3 <-- ... <-- set n - * rigid bodies depend on their world so use BKE_object_handle_update_ex() to also pass along the current rigid body world + * rigid bodies depend on their world so use #BKE_object_handle_update_ex() + * to also pass along the current rigid body world. */ void BKE_object_handle_update(Depsgraph *depsgraph, Scene *scene, Object *ob) { diff --git a/source/blender/blenkernel/intern/object_update.c b/source/blender/blenkernel/intern/object_update.c index c03fffc4098..bcca39cff24 100644 --- a/source/blender/blenkernel/intern/object_update.c +++ b/source/blender/blenkernel/intern/object_update.c @@ -66,7 +66,7 @@ * * Some changes done directly in evaluated object require them to be reset * before being re-evaluated. - * For example, we need to call this before BKE_mesh_new_from_object(), + * For example, we need to call this before #BKE_mesh_new_from_object(), * in case we removed/added modifiers in the evaluated object. */ void BKE_object_eval_reset(Object *ob_eval) @@ -244,8 +244,10 @@ void BKE_object_handle_data_update( BKE_object_eval_boundbox(depsgraph, ob); } -/* TODO(sergey): Ensure that bounding box is already calculated, and move this - * into BKE_object_synchronize_to_original(). */ +/** + * TODO(sergey): Ensure that bounding box is already calculated, and move this + * into #BKE_object_synchronize_to_original(). + */ void BKE_object_eval_boundbox(Depsgraph *depsgraph, Object *object) { if (!DEG_is_active(depsgraph)) { diff --git a/source/blender/blenkernel/intern/pbvh.c b/source/blender/blenkernel/intern/pbvh.c index 7dc772576c5..09fc7c64d6a 100644 --- a/source/blender/blenkernel/intern/pbvh.c +++ b/source/blender/blenkernel/intern/pbvh.c @@ -516,7 +516,7 @@ static void pbvh_build(PBVH *bvh, BB *cb, BBC *prim_bbc, int totprim) * Do a full rebuild with on Mesh data structure. * * \note Unlike mpoly/mloop/verts, looptri is **totally owned** by PBVH (which means it may rewrite it if needed, - * see BKE_pbvh_apply_vertCos(). + * see #BKE_pbvh_apply_vertCos(). */ void BKE_pbvh_build_mesh( PBVH *bvh, const MPoly *mpoly, const MLoop *mloop, MVert *verts, diff --git a/source/blender/blenkernel/intern/softbody.c b/source/blender/blenkernel/intern/softbody.c index 0d8b2381572..2e0d4719339 100644 --- a/source/blender/blenkernel/intern/softbody.c +++ b/source/blender/blenkernel/intern/softbody.c @@ -725,8 +725,9 @@ static void add_bp_springlist(BodyPoint *bp, int springID) } } -/* do this once when sb is build - * it is O(N^2) so scanning for springs every iteration is too expensive +/** + * Do this once when sb is build it is `O(N^2)` + * so scanning for springs every iteration is too expensive. */ static void build_bps_springlist(Object *ob) { diff --git a/source/blender/blenkernel/intern/tracking_stabilize.c b/source/blender/blenkernel/intern/tracking_stabilize.c index 5e7f2421428..6a0dbefd340 100644 --- a/source/blender/blenkernel/intern/tracking_stabilize.c +++ b/source/blender/blenkernel/intern/tracking_stabilize.c @@ -266,12 +266,13 @@ static StabContext *initialize_stabilization_working_context(MovieClip *clip) return ctx; } -/* Discard all private working data attached to this call context. - * NOTE: We allocate the record for the per track baseline contribution - * locally for each call context (i.e. call to - * BKE_tracking_stabilization_data_get() - * Thus it is correct to discard all allocations found within the - * corresponding _local_ GHash +/** + * Discard all private working data attached to this call context. + * + * \note We allocate the record for the per track baseline contribution + * locally for each call context (i.e. call to #BKE_tracking_stabilization_data_get) + * Thus it is correct to discard all allocations found within the + * corresponding _local_ GHash. */ static void discard_stabilization_working_context(StabContext *ctx) { -- cgit v1.2.3