Cleanup: doxy comments
authorCampbell Barton <ideasman42@gmail.com>
Sun, 14 Apr 2019 08:48:42 +0000 (10:48 +0200)
committerCampbell Barton <ideasman42@gmail.com>
Sun, 14 Apr 2019 08:48:42 +0000 (10:48 +0200)
Use doxy references to function and enums,
also correct some names which became out of sync.

50 files changed:
intern/ghost/intern/GHOST_SystemCocoa.mm
intern/ghost/intern/GHOST_SystemWin32.cpp
source/blender/blenfont/intern/blf_font.c
source/blender/blenkernel/BKE_blender_version.h
source/blender/blenkernel/intern/armature.c
source/blender/blenkernel/intern/collection.c
source/blender/blenkernel/intern/constraint.c
source/blender/blenkernel/intern/crazyspace.c
source/blender/blenkernel/intern/image.c
source/blender/blenkernel/intern/library_query.c
source/blender/blenkernel/intern/mesh_validate.c
source/blender/blenkernel/intern/object.c
source/blender/blenkernel/intern/object_update.c
source/blender/blenkernel/intern/pbvh.c
source/blender/blenkernel/intern/softbody.c
source/blender/blenkernel/intern/tracking_stabilize.c
source/blender/blenlib/intern/BLI_ghash.c
source/blender/blenlib/intern/edgehash.c
source/blender/blenlib/intern/math_matrix.c
source/blender/blenlib/intern/winstuff_dir.c
source/blender/blenloader/intern/readfile.c
source/blender/collada/BCAnimationSampler.cpp
source/blender/draw/modes/pose_mode.c
source/blender/editors/animation/keyframes_general.c
source/blender/editors/animation/keyframing.c
source/blender/editors/armature/armature_utils.c
source/blender/editors/curve/editcurve.c
source/blender/editors/gpencil/gpencil_utils.c
source/blender/editors/include/ED_keyframing.h
source/blender/editors/include/ED_numinput.h
source/blender/editors/interface/interface_align.c
source/blender/editors/lattice/editlattice_tools.c
source/blender/editors/space_clip/clip_editor.c
source/blender/editors/space_text/text_draw.c
source/blender/editors/space_text/text_format_lua.c
source/blender/editors/space_text/text_format_pov.c
source/blender/editors/space_text/text_format_pov_ini.c
source/blender/editors/space_text/text_format_py.c
source/blender/editors/space_view3d/view3d_iterators.c
source/blender/editors/space_view3d/view3d_project.c
source/blender/editors/uvedit/uvedit_ops.c
source/blender/gpu/GPU_immediate.h
source/blender/gpu/intern/gpu_uniformbuffer.c
source/blender/makesdna/DNA_anim_types.h
source/blender/makesdna/DNA_object_force_types.h
source/blender/makesdna/intern/dna_genfile.c
source/blender/makesrna/intern/rna_access.c
source/blender/render/intern/source/multires_bake.c
source/blender/windowmanager/intern/wm_event_system.c
source/blender/windowmanager/intern/wm_init_exit.c

index b847cac..8b270c1 100644 (file)
@@ -648,7 +648,7 @@ GHOST_IWindow* GHOST_SystemCocoa::createWindow(
 
 /**
  * Create a new offscreen context.
- * Never explicitly delete the context, use disposeContext() instead.
+ * Never explicitly delete the context, use #disposeContext() instead.
  * \return  The new context (or 0 if creation failed).
  */
 GHOST_IContext *
index 12d58b0..35a9cfa 100644 (file)
@@ -304,8 +304,8 @@ GHOST_IWindow *GHOST_SystemWin32::createWindow(
 
 /**
  * Create a new offscreen context.
- * Never explicitly delete the window, use disposeContext() instead.
- * \return  The new context (or 0 if creation failed).
+ * Never explicitly delete the window, use #disposeContext() instead.
+ * \return The new context (or 0 if creation failed).
  */
 GHOST_IContext *GHOST_SystemWin32::createOffscreenContext()
 {
index 9f81c41..06904ee 100644 (file)
@@ -74,11 +74,12 @@ static SpinLock ft_lib_mutex;
 /* -------------------------------------------------------------------- */
 /** \name Glyph Batching
  * \{ */
+
 /**
  * Drawcalls are precious! make them count!
  * Since most of the Text elems are not covered by other UI elements, we can
  * group some strings together and render them in one drawcall. This behavior
- * is on demand only, between BLF_batch_start() and BLF_batch_end().
+ * is on demand only, between #BLF_batch_draw_begin() and #BLF_batch_draw_end().
  */
 static void blf_batch_draw_init(void)
 {
index 9c47cc9..1b56e20 100644 (file)
  * \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__ */
index 5123b15..890a623 100644 (file)
@@ -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];
index 336a473..eadf190 100644 (file)
@@ -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.
  */
index 7d9a6c2..e8a4983 100644 (file)
@@ -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)
index 5dd5e01..4aa3b70 100644 (file)
@@ -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,
index b00e4cb..0205f27 100644 (file)
@@ -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
index 4fc1ea6..b7ae8ee 100644 (file)
@@ -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)
 {
index a5aa198..295b651 100644 (file)
@@ -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;
index 9985c80..6e9c8ec 100644 (file)
@@ -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)
 {
index c03fffc..bcca39c 100644 (file)
@@ -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)) {
index 7dc7725..09fc7c6 100644 (file)
@@ -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,
index 0d8b238..2e0d471 100644 (file)
@@ -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)
 {
index 5e7f242..6a0dbef 100644 (file)
@@ -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)
 {
index af3a7a4..ae1c6e0 100644 (file)
@@ -1045,7 +1045,7 @@ void BLI_ghash_flag_clear(GHash *gh, uint flag)
 /**
  * Create a new GHashIterator. The hash table must not be mutated
  * while the iterator is in use, and the iterator will step exactly
- * BLI_ghash_len(gh) times before becoming done.
+ * #BLI_ghash_len(gh) times before becoming done.
  *
  * \param gh: The GHash to iterate over.
  * \return Pointer to a new DynStr.
@@ -1060,7 +1060,7 @@ GHashIterator *BLI_ghashIterator_new(GHash *gh)
 /**
  * Init an already allocated GHashIterator. The hash table must not
  * be mutated while the iterator is in use, and the iterator will
- * step exactly BLI_ghash_len(gh) times before becoming done.
+ * step exactly #BLI_ghash_len(gh) times before becoming done.
  *
  * \param ghi: The GHashIterator to initialize.
  * \param gh: The GHash to iterate over.
index 55c9a18..564090f 100644 (file)
@@ -314,7 +314,7 @@ void *BLI_edgehash_lookup_default(EdgeHash *eh, uint v0, uint v1, void *default_
  * Return value for given edge (\a v0, \a v1), or NULL if
  * if key does not exist in hash. (If need exists
  * to differentiate between key-value being NULL and
- * lack of key then see BLI_edgehash_lookup_p().
+ * lack of key then see #BLI_edgehash_lookup_p().
  */
 void *BLI_edgehash_lookup(EdgeHash *eh, uint v0, uint v1)
 {
index f21d883..d750ae4 100644 (file)
@@ -2555,20 +2555,20 @@ void invert_m4_m4_safe(float Ainv[4][4], const float A[4][4])
 }
 
 /**
- * SpaceTransform struct encapsulates all needed data to convert between two coordinate spaces
+ * #SpaceTransform struct encapsulates all needed data to convert between two coordinate spaces
  * (where conversion can be represented by a matrix multiplication).
  *
  * A SpaceTransform is initialized using:
- *   BLI_SPACE_TRANSFORM_SETUP(&data,  ob1, ob2)
+ * - #BLI_SPACE_TRANSFORM_SETUP(&data,  ob1, ob2)
  *
  * After that the following calls can be used:
- *   BLI_space_transform_apply(&data, co);  // converts a coordinate in ob1 space to the corresponding ob2 space
- *   BLI_space_transform_invert(&data, co);  // converts a coordinate in ob2 space to the corresponding ob1 space
+ * - #BLI_space_transform_apply(&data, co);  // converts a coordinate in ob1 space to the corresponding ob2 space.
+ * - #BLI_space_transform_invert(&data, co);  // converts a coordinate in ob2 space to the corresponding ob1 space.
  *
- * Same concept as BLI_space_transform_apply and BLI_space_transform_invert, but no is normalized after conversion
+ * Same concept as #BLI_space_transform_apply and #BLI_space_transform_invert, but no is normalized after conversion
  * (and not translated at all!):
- *   BLI_space_transform_apply_normal(&data, no);
- *   BLI_space_transform_invert_normal(&data, no);
+ * - #BLI_space_transform_apply_normal(&data, no);
+ * - #BLI_space_transform_invert_normal(&data, no);
  */
 
 /**
index b302eae..9c1a51f 100644 (file)
@@ -54,9 +54,10 @@ struct __dirstream {
        struct dirent direntry;
 };
 
-/* Note: MinGW (FREE_WINDOWS) has opendir() and _wopendir(), and only the
- * latter accepts a path name of wchar_t type.  Rather than messing up with
- * extra #ifdef's here and there, Blender's own implementations of opendir()
+/**
+ * \note MinGW (FREE_WINDOWS) has #opendir() and #_wopendir(), and only the
+ * latter accepts a path name of #wchar_t type. Rather than messing up with
+ * extra #ifdef's here and there, Blender's own implementations of #opendir()
  * and related functions are used to properly support paths with non-ASCII
  * characters. (kjym3)
  */
index ea6ac1b..2543271 100644 (file)
@@ -1628,7 +1628,7 @@ bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, cha
  *
  * \param filepath: The path of the file to extract thumbnail from.
  * \return The raw thumbnail
- * (MEM-allocated, as stored in file, use BKE_main_thumbnail_to_imbuf() to convert it to ImBuf image).
+ * (MEM-allocated, as stored in file, use #BKE_main_thumbnail_to_imbuf() to convert it to ImBuf image).
  */
 BlendThumbnail *BLO_thumbnail_from_file(const char *filepath)
 {
index afc3719..7e504a0 100644 (file)
@@ -395,9 +395,9 @@ void BCAnimationSampler::generate_transforms(Object *ob, Bone *bone, BCAnimation
 }
 
 /**
- * Collect all keyframes from all animation curves related to the object
- * The bc_get... functions check for NULL and correct object type
- * The add_keyframes_from() function checks for NULL
+ * Collect all keyframes from all animation curves related to the object.
+ * The bc_get... functions check for NULL and correct object type.
+ * The #add_keyframes_from() function checks for NULL.
  */
 void BCAnimationSampler::initialize_keyframes(BCFrameSet &frameset, Object *ob)
 {
index cb90f94..c445335 100644 (file)
 #include "draw_mode_engines.h"
 
 /* *********** LISTS *********** */
-/* All lists are per viewport specific datas.
+/**
+ * All lists are per viewport specific datas.
  * They are all free when viewport changes engines
- * or is free itself. Use POSE_engine_init() to
- * initialize most of them and POSE_cache_init()
- * for POSE_PassList */
+ * or is free itself. Use #POSE_engine_init() to
+ * initialize most of them and #POSE_cache_init()
+ * for #POSE_PassList
+ */
 
 typedef struct POSE_PassList {
        struct DRWPass *bone_solid[2];
index d186a0b..c9e672a 100644 (file)
 
 /* **************************************************** */
 
-/* Only delete the nominated keyframe from provided F-Curve.
+/**
+ * Only delete the nominated keyframe from provided F-Curve.
  * Not recommended to be used many times successively. For that
- * there is delete_fcurve_keys().
+ * there is #delete_fcurve_keys().
  */
 void delete_fcurve_key(FCurve *fcu, int index, bool do_recalc)
 {
index a86538f..bc63004 100644 (file)
@@ -449,13 +449,13 @@ int insert_bezt_fcurve(FCurve *fcu, const BezTriple *bezt, eInsertKeyFlags flag)
 }
 
 /**
- * This function is a wrapper for insert_bezt_fcurve_internal(), and should be used when
+ * This function is a wrapper for #insert_bezt_fcurve(), and should be used when
  * adding a new keyframe to a curve, when the keyframe doesn't exist anywhere else yet.
  * It returns the index at which the keyframe was added.
  *
- * \param keyframe_type: The type of keyframe (eBezTriple_KeyframeType)
+ * \param keyframe_type: The type of keyframe (#eBezTriple_KeyframeType).
  * \param flag: Optional flags (eInsertKeyFlags) for controlling how keys get added
- *              and/or whether updates get done
+ * and/or whether updates get done.
  */
 int insert_vert_fcurve(FCurve *fcu, float x, float y, eBezTriple_KeyframeType keyframe_type, eInsertKeyFlags flag)
 {
index 6b09912..465209e 100644 (file)
@@ -547,13 +547,16 @@ EditBone *make_boneList(ListBase *edbo, ListBase *bones, struct Bone *actBone)
        return active;
 }
 
-/* This function:
- *     - sets local head/tail rest locations using parent bone's arm_mat.
- *     - calls BKE_armature_where_is_bone() which uses parent's transform (arm_mat) to define this bone's transform.
- *     - fixes (converts) EditBone roll into Bone roll.
- *     - calls again BKE_armature_where_is_bone(), since roll fiddling may have changed things for our bone...
- * Note that order is crucial here, we can only handle child if all its parents in chain have already been handled
- * (this is ensured by recursive process). */
+/**
+ * This function:
+ * - Sets local head/tail rest locations using parent bone's arm_mat.
+ * - Calls #BKE_armature_where_is_bone() which uses parent's transform (arm_mat) to define this bone's transform.
+ * - Fixes (converts) EditBone roll into Bone roll.
+ * - Calls again #BKE_armature_where_is_bone(), since roll fiddling may have changed things for our bone...
+ *
+ * \note The order is crucial here, we can only handle child
+ * if all its parents in chain have already been handled (this is ensured by recursive process).
+ */
 static void armature_finalize_restpose(ListBase *bonelist, ListBase *editbonelist)
 {
        Bone *curBone;
index 10729ec..4aaf0dc 100644 (file)
@@ -2697,7 +2697,7 @@ static void smooth_single_bezt(
 }
 
 /**
- * Same as smooth_single_bezt(), keep in sync
+ * Same as #smooth_single_bezt(), keep in sync.
  */
 static void smooth_single_bp(
         BPoint *bp,
index 44510a3..f582b52 100644 (file)
@@ -216,7 +216,7 @@ bGPdata *ED_gpencil_data_get_active_direct(ID *screen_id, ScrArea *sa, Scene *sc
 /**
  * Get the active Grease Pencil datablock
  * \note This is the original (bmain) copy of the datablock, stored in files.
- *       Do not use for reading evaluated copies of GP Objects data
+ * Do not use for reading evaluated copies of GP Objects data
  */
 bGPdata *ED_gpencil_data_get_active(const bContext *C)
 {
@@ -228,9 +228,9 @@ bGPdata *ED_gpencil_data_get_active(const bContext *C)
  * Get the evaluated copy of the active Grease Pencil datablock (where applicable)
  * - For the 3D View (i.e. "GP Objects"), this gives the evaluated copy of the GP datablock
  *   (i.e. a copy of the active GP datablock for the active object, where modifiers have been
- *   applied). This is needed to correctly work with "Copy-on-Write"
+ *   applied). This is needed to correctly work with "Copy-on-Write".
  * - For all other editors (i.e. "GP Annotations"), this just gives the active datablock
- *   like for ED_gpencil_data_get_active()
+ *   like for #ED_gpencil_data_get_active()
  */
 bGPdata *ED_gpencil_data_get_active_evaluated(const bContext *C)
 {
@@ -640,13 +640,13 @@ void gp_point_to_xy(
 /**
  * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D)
  *
- * Just like gp_point_to_xy(), except the resulting coordinates are floats not ints.
+ * Just like #gp_point_to_xy(), except the resulting coordinates are floats not ints.
  * Use this version to solve "stair-step" artifacts which may arise when roundtripping the calculations.
  *
- * \param r_x: [out] The screen-space x-coordinate of the point
- * \param r_y: [out] The screen-space y-coordinate of the point
+ * \param r_x: [out] The screen-space x-coordinate of the point.
+ * \param r_y: [out] The screen-space y-coordinate of the point.
  *
- * \warning This assumes that the caller has already checked whether the stroke in question can be drawn
+ * \warning This assumes that the caller has already checked whether the stroke in question can be drawn.
  */
 void gp_point_to_xy_fl(
         const GP_SpaceConversion *gsc, const bGPDstroke *gps, const bGPDspoint *pt,
@@ -808,9 +808,9 @@ bool gp_point_xy_to_3d(const GP_SpaceConversion *gsc, Scene *scene, const float
  * Convert tGPspoint (temporary 2D/screenspace point data used by GP modal operators)
  * to 3D coordinates.
  *
- * \param point2D: The screenspace 2D point data to convert
- * \param depth: Depth array (via ED_view3d_autodist_depth())
- * \param[out] r_out: The resulting 2D point data
+ * \param point2D: The screenspace 2D point data to convert.
+ * \param depth: Depth array (via #ED_view3d_autodist_depth()).
+ * \param[out] r_out: The resulting 2D point data.
  */
 void gp_stroke_convertcoords_tpoint(
         Scene *scene, ARegion *ar,
index 51dfa3c..5191978 100644 (file)
@@ -377,11 +377,12 @@ bool fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter);
  */
 bool fcurve_is_changed(struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float frame);
 
-/* Main Keyframe Checking API call:
+/**
+ * Main Keyframe Checking API call:
  * Checks whether a keyframe exists for the given ID-block one the given frame.
  * - It is recommended to call this method over the other keyframe-checkers directly,
  *   in case some detail of the implementation changes...
- * - frame: the value of this is quite often result of BKE_scene_frame_get()
+ * - frame: the value of this is quite often result of #BKE_scene_frame_get()
  */
 bool id_frame_has_keyframe(struct ID *id, float frame, short filter);
 
index 5f90996..d4cb211 100644 (file)
@@ -72,15 +72,18 @@ enum {
 
 struct UnitSettings;
 
-/*********************** NumInput ********************************/
-
-/* There are important things to note here for code using numinput:
- * * Values passed to applyNumInput() should be valid and are stored as default ones (val_org), if it is not EDITED.
- * * bool returned by applyNumInput should be used to decide whether to apply numinput-specific post-process to data.
- * * *Once applyNumInput has been called*, hasNumInput returns a valid value to decide whether to use numinput
- *   as drawstr source or not (i.e. to call outputNumInput).
+/* -------------------------------------------------------------------- */
+/** \name NumInput
+ * \{ */
+
+/**
+ * There are important things to note here for code using numinput:
+ * - Values passed to #applyNumInput() should be valid and are stored as default ones (val_org), if it is not EDITED.
+ * - bool returned by #applyNumInput should be used to decide whether to apply numinput-specific post-process to data.
+ * - Once #applyNumInput has been called, #hasNumInput returns a valid value to decide whether to use numinput
+ *   as drawstr source or not (i.e. to call #outputNumInput).
  *
- * Those two steps have to be separated (so do not use a common call to hasNumInput() to do both in the same time!).
+ * Those two steps have to be separated (so do not use a common call to #hasNumInput() to do both in the same time!).
  */
 
 void initNumInput(NumInput *n);
@@ -94,4 +97,6 @@ bool handleNumInput(struct bContext *C, NumInput *n, const struct wmEvent *event
 
 bool user_string_to_number(bContext *C, const char *str, const struct UnitSettings *unit, int type, double *r_value);
 
+/** \} */
+
 #endif  /* __ED_NUMINPUT_H__ */
index 8e7dc79..9e1563e 100644 (file)
@@ -260,7 +260,7 @@ static void block_align_proximity_compute(ButAlign *butal, ButAlign *butal_other
  * Here, BUT 3 RIGHT side would not get 'dragged' to align with BUT 1 RIGHT side, since BUT 3 has not RIGHT neighbor.
  * So, this function, when called with BUT 1, will 'walk' the whole column in \a side_s1 direction (TOP or DOWN when
  * called for RIGHT side), and force buttons like BUT 3 to align as needed, if BUT 1 and BUT 3 were detected as needing
- * top-right corner stitching in \a block_align_proximity_compute() step.
+ * top-right corner stitching in #block_align_proximity_compute() step.
  *
  * \note To avoid doing this twice, some stitching flags are cleared to break the 'stitching connection'
  *       between neighbors.
index 0d57b94..edb7979 100644 (file)
@@ -133,9 +133,9 @@ typedef enum eLattice_FlipAxes {
 } eLattice_FlipAxes;
 
 /**
- * Flip midpoint value so that relative distances between midpoint and neighbor-pair is maintained
- * ! Assumes that uvw <=> xyz (i.e. axis-aligned index-axes with coordinate-axes)
- * - Helper for lattice_flip_exec()
+ * Flip midpoint value so that relative distances between midpoint and neighbor-pair is maintained.
+ * Assumes that uvw <=> xyz (i.e. axis-aligned index-axes with coordinate-axes).
+ * - Helper for #lattice_flip_exec()
  */
 static void lattice_flip_point_value(Lattice *lt, int u, int v, int w, float mid, eLattice_FlipAxes axis)
 {
@@ -151,8 +151,8 @@ static void lattice_flip_point_value(Lattice *lt, int u, int v, int w, float mid
 }
 
 /**
- * Swap pairs of lattice points along a specified axis
- * - Helper for lattice_flip_exec()
+ * Swap pairs of lattice points along a specified axis.
+ * - Helper for #lattice_flip_exec()
  */
 static void lattice_swap_point_pairs(Lattice *lt, int u, int v, int w, float mid, eLattice_FlipAxes axis)
 {
index 79a159b..7cfc525 100644 (file)
@@ -578,7 +578,7 @@ void ED_clip_point_stable_pos(SpaceClip *sc, ARegion *ar, float x, float y, floa
 }
 
 /**
- * \brief the reverse of ED_clip_point_stable_pos(), gets the marker region coords.
+ * \brief the reverse of #ED_clip_point_stable_pos(), gets the marker region coords.
  * better name here? view_to_track / track_to_view or so?
  */
 void ED_clip_point_stable_pos__reverse(SpaceClip *sc, ARegion *ar, const float co[2], float r_co[2])
index 87bbefd..1b49e63 100644 (file)
@@ -154,14 +154,19 @@ static void format_draw_color(const TextDrawContext *tdc, char formatchar)
 
 /************************** draw text *****************************/
 
-/* Notes on word-wrap
+/**
+ * Notes on word-wrap
  * --
- * All word-wrap functions follow the algorithm below to maintain consistency.
- *     line        The line to wrap (tabs converted to spaces)
- *     view_width    The maximum number of characters displayable in the region
- *                 This equals region_width/font_width for the region
- *     wrap_chars    Characters that allow wrapping. This equals [' ', '\t', '-']
+ * All word-wrap functions follow the algorithm below to maintain consistency:
+ * - line:
+ *   The line to wrap (tabs converted to spaces)
+ * - view_width:
+ *   The maximum number of characters displayable in the region
+ *   This equals region_width/font_width for the region
+ * - wrap_chars:
+ *   Characters that allow wrapping. This equals [' ', '\t', '-']
  *
+ * \code{.py}
  * def wrap(line, view_width, wrap_chars):
  *     draw_start = 0
  *     draw_end = view_width
@@ -175,6 +180,7 @@ static void format_draw_color(const TextDrawContext *tdc, char formatchar)
  *             draw_end = pos+1
  *         pos += 1
  *     print line[draw_start:]
+ * \encode
  */
 
 int wrap_width(const SpaceText *st, ARegion *ar)
index 7118b8b..4b25c5d 100644 (file)
 
 /* *** Lua Keywords (for format_line) *** */
 
-/* Checks the specified source string for a Lua keyword (minus boolean & 'nil').
+/**
+ * Checks the specified source string for a Lua keyword (minus boolean & 'nil').
  * This name must start at the beginning of the source string and must be
- * followed by a non-identifier (see text_check_identifier(char)) or null char.
+ * followed by a non-identifier (see #text_check_identifier(char)) or null char.
  *
  * If a keyword is found, the length of the matching word is returned.
  * Otherwise, -1 is returned.
@@ -40,7 +41,6 @@
  * See:
  * http://www.lua.org/manual/5.1/manual.html#2.1
  */
-
 static int txtfmt_lua_find_keyword(const char *string)
 {
        int i, len;
@@ -71,9 +71,10 @@ static int txtfmt_lua_find_keyword(const char *string)
        return i;
 }
 
-/* Checks the specified source string for a Lua special name/function. This
+/**
+ * Checks the specified source string for a Lua special name/function. This
  * name must start at the beginning of the source string and must be followed
- * by a non-identifier (see text_check_identifier(char)) or null character.
+ * by a non-identifier (see *text_check_identifier(char)) or null character.
  *
  * If a special name is found, the length of the matching name is returned.
  * Otherwise, -1 is returned.
@@ -81,7 +82,6 @@ static int txtfmt_lua_find_keyword(const char *string)
  * See:
  * http://www.lua.org/manual/5.1/manual.html#5.1
  */
-
 static int txtfmt_lua_find_specialvar(const char *string)
 {
        int i, len;
index da10c86..2435d2f 100644 (file)
 
 /* *** POV Keywords (for format_line) *** */
 
-/* Checks the specified source string for a POV keyword (minus boolean & 'nil').
+/**
+ * Checks the specified source string for a POV keyword (minus boolean & 'nil').
  * This name must start at the beginning of the source string and must be
- * followed by a non-identifier (see text_check_identifier(char)) or null char.
+ * followed by a non-identifier (see #text_check_identifier(char)) or null char.
  *
  * If a keyword is found, the length of the matching word is returned.
  * Otherwise, -1 is returned.
@@ -40,7 +41,6 @@
  * See:
  * http://www.povray.org/documentation/view/3.7.0/212/
  */
-
 static int txtfmt_pov_find_keyword(const char *string)
 {
        int i, len;
@@ -467,9 +467,10 @@ static int txtfmt_pov_find_reserved_builtins(const char *string)
 }
 
 
-/* Checks the specified source string for a POV modifiers. This
+/**
+ * Checks the specified source string for a POV modifiers. This
  * name must start at the beginning of the source string and must be followed
- * by a non-identifier (see text_check_identifier(char)) or null character.
+ * by a non-identifier (see #text_check_identifier(char)) or null character.
  *
  * If a special name is found, the length of the matching name is returned.
  * Otherwise, -1 is returned.
@@ -477,7 +478,6 @@ static int txtfmt_pov_find_reserved_builtins(const char *string)
  * See:
  * http://www.povray.org/documentation/view/3.7.0/212/
  */
-
 static int txtfmt_pov_find_specialvar(const char *string)
 {
        int i, len;
index e41fd94..da69a35 100644 (file)
 
 /* *** POV INI Keywords (for format_line) *** */
 
-/* Checks the specified source string for a POV INI keyword (minus boolean & 'nil').
+/**
+ * Checks the specified source string for a POV INI keyword (minus boolean & 'nil').
  * This name must start at the beginning of the source string and must be
- * followed by a non-identifier (see text_check_identifier(char)) or null char.
+ * followed by a non-identifier (see #text_check_identifier(char)) or null char.
  *
  * If a keyword is found, the length of the matching word is returned.
  * Otherwise, -1 is returned.
@@ -40,7 +41,6 @@
  * See:
  * http://www.povray.org/documentation/view/3.7.0/212/
  */
-
 static int txtfmt_ini_find_keyword(const char *string)
 {
        int i, len;
index 85c3c42..87b3835 100644 (file)
 
 /* *** Local Functions (for format_line) *** */
 
-/* Checks the specified source string for a Python built-in function name. This
+/**
+ * Checks the specified source string for a Python built-in function name. This
  * name must start at the beginning of the source string and must be followed by
- * a non-identifier (see text_check_identifier(char)) or null character.
+ * a non-identifier (see #text_check_identifier(char)) or null character.
  *
  * If a built-in function is found, the length of the matching name is returned.
  * Otherwise, -1 is returned.
@@ -40,7 +41,6 @@
  * See:
  * http://docs.python.org/py3k/reference/lexical_analysis.html#keywords
  */
-
 static int txtfmt_py_find_builtinfunc(const char *string)
 {
        int i, len;
index 0054680..daa1cd3 100644 (file)
@@ -79,10 +79,12 @@ typedef struct foreachScreenFace_userData {
 } foreachScreenFace_userData;
 
 
-/* Note! - foreach funcs should be called while drawing or directly after
- * if not, ED_view3d_init_mats_rv3d() can be used for selection tools
+/**
+ * \note foreach funcs should be called while drawing or directly after
+ * if not, #ED_view3d_init_mats_rv3d() can be used for selection tools
  * but would not give correct results with dupli's for eg. which don't
- * use the object matrix in the usual way */
+ * use the object matrix in the usual way.
+ */
 
 /* ------------------------------------------------------------------------ */
 
index 760cbb3..e5f8ac1 100644 (file)
@@ -582,7 +582,7 @@ bool ED_view3d_win_to_3d_on_plane_int(
 
 /**
  * Calculate a 3d difference vector from 2d window offset.
- * note that ED_view3d_calc_zfac() must be called first to determine
+ * note that #ED_view3d_calc_zfac() must be called first to determine
  * the depth used to calculate the delta.
  * \param ar: The region (used for the window width and height).
  * \param mval: The area relative 2d difference (such as event->mval[0] - other_x).
index a4247ec..1bcf600 100644 (file)
@@ -2827,10 +2827,12 @@ static void UV_OT_select_linked_pick(wmOperatorType *ot)
 /** \name Select Split Operator
  * \{ */
 
-/* note: this is based on similar use case to MESH_OT_split(), which has a similar effect
+/**
+ * \note This is based on similar use case to #MESH_OT_split(), which has a similar effect
  * but in this case they are not joined to begin with (only having the behavior of being joined)
- * so its best to call this uv_select_split() instead of just split(), but assigned to the same key
- * as MESH_OT_split - Campbell */
+ * so its best to call this #uv_select_split() instead of just split(), but assigned to the same key
+ * as #MESH_OT_split - Campbell.
+ */
 static int uv_select_split_exec(bContext *C, wmOperator *op)
 {
        Scene *scene = CTX_data_scene(C);
index 57912c0..b7d2901 100644 (file)
@@ -124,8 +124,10 @@ void immUniformColor3ubv(const unsigned char rgb[3]);
 void immUniformColor3ubvAlpha(const unsigned char rgb[3], unsigned char a);
 void immUniformColor4ubv(const unsigned char rgba[4]);
 
-/* Extend immBindProgram to use Blender’s library of built-in shader programs.
- * Use immUnbindProgram() when done. */
+/**
+ * Extend #immBindProgram to use Blender’s library of built-in shader programs.
+ * Use #immUnbindProgram() when done.
+ */
 void immBindBuiltinProgram(eGPUBuiltinShader shader_id);
 
 /* Extend immUniformColor to take Blender's themes */
index 4753972..a5559b2 100644 (file)
@@ -107,7 +107,7 @@ GPUUniformBuffer *GPU_uniformbuffer_create(int size, const void *data, char err_
  * Create dynamic UBO from parameters
  * Return NULL if failed to create or if \param inputs: is empty.
  *
- * \param inputs: ListBase of BLI_genericNodeN(GPUInput)
+ * \param inputs: ListBase of #BLI_genericNodeN(#GPUInput).
  */
 GPUUniformBuffer *GPU_uniformbuffer_dynamic_create(ListBase *inputs, char err_out[256])
 {
index ccc0b2e..c2f6909 100644 (file)
@@ -1107,7 +1107,7 @@ typedef enum eAnimData_Flag {
 /* Base Struct for Anim ------------------------------------- */
 
 /**
- * Used for BKE_animdata_from_id()
+ * Used for #BKE_animdata_from_id()
  * All ID-datablocks which have their own 'local' AnimData
  * should have the same arrangement in their structs.
  */
index 4b276a0..edd5d30 100644 (file)
@@ -185,11 +185,12 @@ typedef struct EffectorWeights {
 /* EffectorWeights->flag */
 #define EFF_WEIGHT_DO_HAIR             1
 
-/* Point cache file data types:
- * - used as (1 << flag) so poke jahka if you reach the limit of 15
- * - to add new data types update:
- *   - BKE_ptcache_data_size()
- *   - ptcache_file_init_pointers()
+/**
+ * Point cache file data types:
+ * - Used as `(1 << flag)` so poke jahka if you reach the limit of 15.
+ * - To add new data types update:
+ *   - #BKE_ptcache_data_size()
+ *   - #ptcache_file_pointers_init()
  */
 #define BPHYS_DATA_INDEX               0
 #define BPHYS_DATA_LOCATION            1
index b31fa8e..863aebd 100644 (file)
@@ -922,7 +922,7 @@ static bool elem_exists(
  *
  * Passing olddata=NULL doesn't work reliably for existence checks; it will
  * return NULL both when the field is found at offset 0 and when it is not
- * found at all. For field existence checks, use elem_exists() instead.
+ * found at all. For field existence checks, use #elem_exists() instead.
  *
  * \param sdna: Old SDNA
  * \param type: Current field type name
index 1d39198..b1c5ef6 100644 (file)
@@ -2063,7 +2063,7 @@ bool RNA_property_animated(PointerRNA *ptr, PropertyRNA *prop)
 }
 
 /** \note Does not take into account editable status, this has to be checked separately
- * (using RNA_property_edtiable_flag() usually). */
+ * (using #RNA_property_editable_flag() usually). */
 bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop)
 {
        if (prop->magic == RNA_MAGIC) {
index 632c501..8a8e4bb 100644 (file)
@@ -802,11 +802,14 @@ static void free_normal_data(void *bake_data)
        MEM_freeN(normal_data);
 }
 
-/* MultiresBake callback for normals' baking
- * general idea:
- *   - find coord and normal of point with specified UV in hi-res mesh
- *   - multiply it by tangmat
- *   - vector in color space would be norm(vec) /2 + (0.5, 0.5, 0.5) */
+/**
+ * MultiresBake callback for normals' baking.
+ *
+ * General idea:
+ * - Find coord and normal of point with specified UV in hi-res mesh.
+ * - Multiply it by tangmat.
+ * - Vector in color space would be `norm(vec) / 2 + (0.5, 0.5, 0.5)`.
+ */
 static void apply_tangmat_callback(DerivedMesh *lores_dm, DerivedMesh *hires_dm, void *UNUSED(thread_data),
                                    void *bake_data, ImBuf *ibuf, const int tri_index, const int lvl,
                                    const float st[2], float tangmat[3][3], const int x, const int y)
index aafc839..5d22eb7 100644 (file)
@@ -1084,7 +1084,7 @@ int WM_operator_repeat_interactive(bContext *C, wmOperator *op)
  * \return true if #WM_operator_repeat can run
  * simple check for now but may become more involved.
  * To be sure the operator can run call `WM_operator_poll(C, op->type)` also, since this call
- * checks if WM_operator_repeat() can run at all, not that it WILL run at any time.
+ * checks if #WM_operator_repeat() can run at all, not that it WILL run at any time.
  */
 bool WM_operator_repeat_check(const bContext *UNUSED(C), wmOperator *op)
 {
index 011f0de..f39cb7d 100644 (file)
@@ -403,7 +403,7 @@ static int wm_exit_handler(bContext *C, const wmEvent *event, void *userdata)
 }
 
 /**
- * Cause a delayed WM_exit() call to avoid leaking memory when trying to exit from within operators.
+ * Cause a delayed #WM_exit() call to avoid leaking memory when trying to exit from within operators.
  */
 void wm_exit_schedule_delayed(const bContext *C)
 {