From 9416004092c5db4b16e8c3f241f3ae789c8789bc Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 9 Mar 2022 16:29:22 +1100 Subject: Cleanup: use doxygen comments & sections for animation files --- source/blender/editors/animation/anim_intern.h | 61 +++++++++---- source/blender/editors/animation/keyframing.c | 34 ++++--- source/blender/editors/include/ED_anim_api.h | 119 +++++++++++++------------ 3 files changed, 129 insertions(+), 85 deletions(-) (limited to 'source') diff --git a/source/blender/editors/animation/anim_intern.h b/source/blender/editors/animation/anim_intern.h index e7277c51cd3..8d8d624c69b 100644 --- a/source/blender/editors/animation/anim_intern.h +++ b/source/blender/editors/animation/anim_intern.h @@ -14,49 +14,80 @@ extern ListBase builtin_keyingsets; /* Operator Define Prototypes ------------------- */ -/* Main Keyframe Management operators: - * These handle keyframes management from various spaces. They only make use of - * Keying Sets. - */ +/* -------------------------------------------------------------------- */ +/** \name Main Keyframe Management operators + * + * These handle keyframes management from various spaces. + * They only make use of Keying Sets. + * \{ */ + void ANIM_OT_keyframe_insert(struct wmOperatorType *ot); void ANIM_OT_keyframe_delete(struct wmOperatorType *ot); void ANIM_OT_keyframe_insert_by_name(struct wmOperatorType *ot); void ANIM_OT_keyframe_delete_by_name(struct wmOperatorType *ot); -/* Main Keyframe Management operators: - * These handle keyframes management from various spaces. They will handle the menus - * required for each space. - */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Main Keyframe Management operators + * + * These handle keyframes management from various spaces. + * They will handle the menus required for each space. + * \{ */ + void ANIM_OT_keyframe_insert_menu(struct wmOperatorType *ot); void ANIM_OT_keyframe_delete_v3d(struct wmOperatorType *ot); void ANIM_OT_keyframe_clear_v3d(struct wmOperatorType *ot); -/* Keyframe management operators for UI buttons (RMB menu). */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Keyframe management operators for UI buttons (RMB menu) + * \{ */ + void ANIM_OT_keyframe_insert_button(struct wmOperatorType *ot); void ANIM_OT_keyframe_delete_button(struct wmOperatorType *ot); void ANIM_OT_keyframe_clear_button(struct wmOperatorType *ot); -/* .......... */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name KeyingSet management operators for UI buttons (RMB menu) + * \{ */ -/* KeyingSet management operators for UI buttons (RMB menu) */ void ANIM_OT_keyingset_button_add(struct wmOperatorType *ot); void ANIM_OT_keyingset_button_remove(struct wmOperatorType *ot); -/* KeyingSet management operators for RNA collections/UI buttons */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name KeyingSet management operators for RNA collections/UI buttons + * \{ */ + void ANIM_OT_keying_set_add(struct wmOperatorType *ot); void ANIM_OT_keying_set_remove(struct wmOperatorType *ot); void ANIM_OT_keying_set_path_add(struct wmOperatorType *ot); void ANIM_OT_keying_set_path_remove(struct wmOperatorType *ot); -/* KeyingSet general operators */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name KeyingSet general operators + * \{ */ + void ANIM_OT_keying_set_active_set(struct wmOperatorType *ot); -/* .......... */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Driver management operators for UI buttons (RMB menu) + * \{ */ -/* Driver management operators for UI buttons (RMB menu) */ void ANIM_OT_driver_button_add(struct wmOperatorType *ot); void ANIM_OT_driver_button_remove(struct wmOperatorType *ot); void ANIM_OT_driver_button_edit(struct wmOperatorType *ot); void ANIM_OT_copy_driver_button(struct wmOperatorType *ot); void ANIM_OT_paste_driver_button(struct wmOperatorType *ot); + +/** \} */ diff --git a/source/blender/editors/animation/keyframing.c b/source/blender/editors/animation/keyframing.c index feb78ce293e..90c127b620b 100644 --- a/source/blender/editors/animation/keyframing.c +++ b/source/blender/editors/animation/keyframing.c @@ -244,7 +244,7 @@ FCurve *ED_action_fcurve_ensure(struct Main *bmain, return fcu; } -/* Helper for update_autoflags_fcurve() */ +/** Helper for #update_autoflags_fcurve(). */ static void update_autoflags_fcurve_direct(FCurve *fcu, PropertyRNA *prop) { /* set additional flags for the F-Curve (i.e. only integer values) */ @@ -304,7 +304,8 @@ void update_autoflags_fcurve(FCurve *fcu, bContext *C, ReportList *reports, Poin /* ************************************************** */ /* KEYFRAME INSERTION */ -/* Move the point where a key is about to be inserted to be inside the main cycle range. +/** + * Move the point where a key is about to be inserted to be inside the main cycle range. * Returns the type of the cycle if it is enabled and valid. */ static eFCU_Cycle_Type remap_cyclic_keyframe_location(FCurve *fcu, float *px, float *py) @@ -345,7 +346,7 @@ static eFCU_Cycle_Type remap_cyclic_keyframe_location(FCurve *fcu, float *px, fl return type; } -/* Used to make curves newly added to a cyclic Action cycle with the correct period. */ +/** Used to make curves newly added to a cyclic Action cycle with the correct period. */ static void make_new_fcurve_cyclic(const bAction *act, FCurve *fcu) { /* The curve must contain one (newly-added) keyframe. */ @@ -652,11 +653,13 @@ enum { KEYNEEDED_DELNEXT, } /*eKeyNeededStatus*/; -/* This helper function determines whether a new keyframe is needed */ -/* Cases where keyframes should not be added: - * 1. Keyframe to be added between two keyframes with similar values - * 2. Keyframe to be added on frame where two keyframes are already situated - * 3. Keyframe lies at point that intersects the linear line between two keyframes +/** + * This helper function determines whether a new keyframe is needed. + * + * Cases where keyframes should not be added: + * 1. Keyframe to be added between two keyframes with similar values. + * 2. Keyframe to be added on frame where two keyframes are already situated. + * 3. Keyframe lies at point that intersects the linear line between two keyframes. */ static short new_key_needed(FCurve *fcu, float cFrame, float nValue) { @@ -769,7 +772,7 @@ static short new_key_needed(FCurve *fcu, float cFrame, float nValue) /* ------------------ RNA Data-Access Functions ------------------ */ -/* Try to read value using RNA-properties obtained already */ +/** Try to read value using RNA-properties obtained already. */ static float *setting_get_rna_values( PointerRNA *ptr, PropertyRNA *prop, float *buffer, int buffer_size, int *r_count) { @@ -844,7 +847,8 @@ enum { VISUALKEY_SCA, }; -/* This helper function determines if visual-keyframing should be used when +/** + * This helper function determines if visual-keyframing should be used when * inserting keyframes for the given channel. As visual-keyframing only works * on Object and Pose-Channel blocks, this should only get called for those * blocktypes, when using "standard" keying but 'Visual Keying' option in Auto-Keying @@ -1012,7 +1016,8 @@ static bool visualkey_can_use(PointerRNA *ptr, PropertyRNA *prop) return false; } -/* This helper function extracts the value to use for visual-keyframing +/** + * This helper function extracts the value to use for visual-keyframing * In the event that it is not possible to perform visual keying, try to fall-back * to using the default method. Assumes that all data it has been passed is valid. */ @@ -1305,7 +1310,7 @@ bool insert_keyframe_direct(ReportList *reports, return insert_keyframe_value(reports, &ptr, prop, fcu, anim_eval_context, curval, keytype, flag); } -/* Find or create the FCurve based on the given path, and insert the specified value into it. */ +/** Find or create the #FCurve based on the given path, and insert the specified value into it. */ static bool insert_keyframe_fcurve_value(Main *bmain, ReportList *reports, PointerRNA *ptr, @@ -1829,9 +1834,10 @@ enum { COMMONKEY_MODE_DELETE, } /*eCommonModifyKey_Modes*/; -/* Polling callback for use with ANIM_*_keyframe() operators +/** + * Polling callback for use with `ANIM_*_keyframe()` operators * This is based on the standard ED_operator_areaactive callback, - * except that it does special checks for a few spacetypes too... + * except that it does special checks for a few space-types too. */ static bool modify_key_op_poll(bContext *C) { diff --git a/source/blender/editors/include/ED_anim_api.h b/source/blender/editors/include/ED_anim_api.h index 4b6f5e4cac6..3402d45fa96 100644 --- a/source/blender/editors/include/ED_anim_api.h +++ b/source/blender/editors/include/ED_anim_api.h @@ -51,8 +51,9 @@ struct PropertyRNA; /** \name Context * \{ */ -/* This struct defines a structure used for animation-specific - * 'context' information +/** + * This struct defines a structure used for animation-specific + * 'context' information. */ typedef struct bAnimContext { /** data to be filtered for use in animation editor */ @@ -118,8 +119,9 @@ typedef enum eAnimCont_Types { /** \name Channels * \{ */ -/* This struct defines a structure used for quick and uniform access for - * channels of animation data +/** + * This struct defines a structure used for quick and uniform access for + * channels of animation data. */ typedef struct bAnimListElem { struct bAnimListElem *next, *prev; @@ -257,7 +259,8 @@ typedef enum eAnim_KeyType { ALE_GROUP, /* Action Group summary */ } eAnim_KeyType; -/* Flags for specifying the types of updates (i.e. recalculation/refreshing) that +/** + * Flags for specifying the types of updates (i.e. recalculation/refreshing) that * needs to be performed to the data contained in a channel following editing. * For use with ANIM_animdata_update() */ @@ -379,13 +382,13 @@ typedef enum eAnimFilter_Flags { #define EXPANDED_DRVD(adt) ((adt->flag & ADT_DRIVERS_COLLAPSED) == 0) /* Actions (also used for Dopesheet) */ -/* Action Channel Group */ +/** Action Channel Group. */ #define EDITABLE_AGRP(agrp) (((agrp)->flag & AGRP_PROTECTED) == 0) #define EXPANDED_AGRP(ac, agrp) \ (((!(ac) || ((ac)->spacetype != SPACE_GRAPH)) && ((agrp)->flag & AGRP_EXPANDED)) || \ (((ac) && ((ac)->spacetype == SPACE_GRAPH)) && ((agrp)->flag & AGRP_EXPANDED_G))) #define SEL_AGRP(agrp) (((agrp)->flag & AGRP_SELECTED) || ((agrp)->flag & AGRP_ACTIVE)) -/* F-Curve Channels */ +/** F-Curve Channels. */ #define EDITABLE_FCU(fcu) ((fcu->flag & FCURVE_PROTECTED) == 0) #define SEL_FCU(fcu) (fcu->flag & FCURVE_SELECTED) @@ -394,16 +397,16 @@ typedef enum eAnimFilter_Flags { #define SEL_SHAPEKEY(kb) (kb->flag & KEYBLOCK_SEL) /* Grease Pencil only */ -/* Grease Pencil datablock settings */ +/** Grease Pencil data-block settings. */ #define EXPANDED_GPD(gpd) (gpd->flag & GP_DATA_EXPAND) -/* Grease Pencil Layer settings */ +/** Grease Pencil Layer settings. */ #define EDITABLE_GPL(gpl) ((gpl->flag & GP_LAYER_LOCKED) == 0) #define SEL_GPL(gpl) (gpl->flag & GP_LAYER_SELECT) /* Mask Only */ -/* Grease Pencil datablock settings */ +/** Grease Pencil data-block settings. */ #define EXPANDED_MASK(mask) (mask->flag & MASK_ANIMF_EXPAND) -/* Grease Pencil Layer settings */ +/** Grease Pencil Layer settings. */ #define EDITABLE_MASK(masklay) ((masklay->flag & MASK_LAYERFLAG_LOCKED) == 0) #define SEL_MASKLAY(masklay) (masklay->flag & SELECT) @@ -426,20 +429,20 @@ typedef enum eAnimFilter_Flags { /** \name Channel Defines * \{ */ -/* channel heights */ +/** Channel heights. */ #define ACHANNEL_FIRST_TOP(ac) \ (UI_view2d_scale_get_y(&(ac)->region->v2d) * -UI_TIME_SCRUB_MARGIN_Y - ACHANNEL_SKIP) #define ACHANNEL_HEIGHT(ac) (0.8f * (ac)->yscale_fac * U.widget_unit) #define ACHANNEL_SKIP (0.1f * U.widget_unit) #define ACHANNEL_STEP(ac) (ACHANNEL_HEIGHT(ac) + ACHANNEL_SKIP) -/* Additional offset to give some room at the end. */ +/** Additional offset to give some room at the end. */ #define ACHANNEL_TOT_HEIGHT(ac, item_amount) \ (-ACHANNEL_FIRST_TOP(ac) + ACHANNEL_STEP(ac) * (item_amount + 1)) -/* channel widths */ +/** Channel widths. */ #define ACHANNEL_NAMEWIDTH (10 * U.widget_unit) -/* channel toggle-buttons */ +/** Channel toggle-buttons. */ #define ACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit) /** \} */ @@ -448,7 +451,7 @@ typedef enum eAnimFilter_Flags { /** \name NLA Channel Defines * \{ */ -/* NLA channel heights */ +/** NLA channel heights */ #define NLACHANNEL_FIRST_TOP(ac) \ (UI_view2d_scale_get_y(&(ac)->region->v2d) * -UI_TIME_SCRUB_MARGIN_Y - NLACHANNEL_SKIP) #define NLACHANNEL_HEIGHT(snla) \ @@ -456,14 +459,14 @@ typedef enum eAnimFilter_Flags { (1.2f * U.widget_unit)) #define NLACHANNEL_SKIP (0.1f * U.widget_unit) #define NLACHANNEL_STEP(snla) (NLACHANNEL_HEIGHT(snla) + NLACHANNEL_SKIP) -/* Additional offset to give some room at the end. */ +/** Additional offset to give some room at the end. */ #define NLACHANNEL_TOT_HEIGHT(ac, item_amount) \ (-NLACHANNEL_FIRST_TOP(ac) + NLACHANNEL_STEP(((SpaceNla *)(ac)->sl)) * (item_amount + 1)) -/* channel widths */ +/** Channel widths */ #define NLACHANNEL_NAMEWIDTH (10 * U.widget_unit) -/* channel toggle-buttons */ +/** Channel toggle-buttons */ #define NLACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit) /** \} */ @@ -521,7 +524,7 @@ void ANIM_animdata_freelist(ListBase *anim_data); /** \name Drawing TypeInfo * \{ */ -/* role or level of animchannel in the hierarchy */ +/** Role or level of anim-channel in the hierarchy. */ typedef enum eAnimChannel_Role { /** datablock expander - a "composite" channel type */ ACHANNEL_ROLE_EXPANDER = -1, @@ -561,7 +564,7 @@ typedef enum eAnimChannel_Settings { ACHANNEL_SETTING_ALWAYS_VISIBLE = 8, } eAnimChannel_Settings; -/* Drawing, mouse handling, and flag setting behavior... */ +/** Drawing, mouse handling, and flag setting behavior. */ typedef struct bAnimChannelType { /* -- Type data -- */ /* name of the channel type, for debugging */ @@ -570,30 +573,31 @@ typedef struct bAnimChannelType { eAnimChannel_Role channel_role; /* -- Drawing -- */ - /* get RGB color that is used to draw the majority of the backdrop */ + /** Get RGB color that is used to draw the majority of the backdrop. */ void (*get_backdrop_color)(bAnimContext *ac, bAnimListElem *ale, float r_color[3]); - /* draw backdrop strip for channel */ + /** Draw backdrop strip for channel. */ void (*draw_backdrop)(bAnimContext *ac, bAnimListElem *ale, float yminc, float ymaxc); - /* get depth of indention (relative to the depth channel is nested at) */ + /** Get depth of indention (relative to the depth channel is nested at). */ short (*get_indent_level)(bAnimContext *ac, bAnimListElem *ale); - /* get offset in pixels for the start of the channel (in addition to the indent depth) */ + /** Get offset in pixels for the start of the channel (in addition to the indent depth). */ short (*get_offset)(bAnimContext *ac, bAnimListElem *ale); - /* get name (for channel lists) */ + /** Get name (for channel lists). */ void (*name)(bAnimListElem *ale, char *name); - /* get RNA property+pointer for editing the name */ + /** Get RNA property+pointer for editing the name. */ bool (*name_prop)(bAnimListElem *ale, struct PointerRNA *ptr, struct PropertyRNA **prop); - /* get icon (for channel lists) */ + /** Get icon (for channel lists). */ int (*icon)(bAnimListElem *ale); /* -- Settings -- */ - /* check if the given setting is valid in the current context */ + /** Check if the given setting is valid in the current context. */ bool (*has_setting)(bAnimContext *ac, bAnimListElem *ale, eAnimChannel_Settings setting); - /* get the flag used for this setting */ + /** Get the flag used for this setting. */ int (*setting_flag)(bAnimContext *ac, eAnimChannel_Settings setting, bool *neg); - /* get the pointer to int/short where data is stored, - * with type being sizeof(ptr_data) which should be fine for runtime use... - * - assume that setting has been checked to be valid for current context + /** + * Get the pointer to int/short where data is stored, + * with type being `sizeof(ptr_data)` which should be fine for runtime use. + * - assume that setting has been checked to be valid for current context. */ void *(*setting_ptr)(bAnimListElem *ale, eAnimChannel_Settings setting, short *type); } bAnimChannelType; @@ -720,11 +724,11 @@ bool ANIM_remove_empty_action_from_animdata(struct AnimData *adt); /* flags for Current Frame Drawing */ typedef enum eAnimEditDraw_CurrentFrame { - /* plain time indicator with no special indicators */ + /** Plain time indicator with no special indicators. */ /* DRAWCFRA_PLAIN = 0, */ /* UNUSED */ - /* time indication in seconds or frames */ + /** Time indication in seconds or frames. */ DRAWCFRA_UNIT_SECONDS = (1 << 0), - /* draw indicator extra wide (for timeline) */ + /** Draw indicator extra wide (for timeline). */ DRAWCFRA_WIDE = (1 << 1), } eAnimEditDraw_CurrentFrame; @@ -784,9 +788,9 @@ struct NlaTrack *ANIM_nla_context_track(const struct bContext *C); struct NlaStrip *ANIM_nla_context_strip(const struct bContext *C); struct FCurve *ANIM_graph_context_fcurve(const struct bContext *C); -/* Needed for abstraction between the graph editor and the NLA editor. */ +/** Needed for abstraction between the graph editor and the NLA editor. */ typedef bool (*PanelTypePollFn)(const struct bContext *C, struct PanelType *pt); -/* Avoid including "UI_interface.h" here. */ +/** Avoid including `UI_interface.h` here. */ typedef void (*uiListPanelIDFromDataFunc)(void *data_link, char *r_idname); /** @@ -912,20 +916,21 @@ void ED_nla_postop_refresh(bAnimContext *ac); /* anim_draw.c */ -/* flags for conversion mapping */ +/** Flags for conversion mapping. */ typedef enum eAnimUnitConv_Flags { - /* restore to original internal values */ + /** Restore to original internal values. */ ANIM_UNITCONV_RESTORE = (1 << 0), - /* ignore handles (i.e. only touch main keyframes) */ + /** Ignore handles (i.e. only touch main keyframes). */ ANIM_UNITCONV_ONLYKEYS = (1 << 1), - /* only touch selected BezTriples */ + /** Only touch selected BezTriples. */ ANIM_UNITCONV_ONLYSEL = (1 << 2), - /* only touch selected vertices */ + /** Only touch selected vertices. */ ANIM_UNITCONV_SELVERTS = (1 << 3), /* ANIM_UNITCONV_SKIPKNOTS = (1 << 4), */ /* UNUSED */ - /* Scale FCurve i a way it fits to -1..1 space */ + /** Scale FCurve i a way it fits to -1..1 space. */ ANIM_UNITCONV_NORMALIZE = (1 << 5), - /* Only when normalization is used: use scale factor from previous run, + /** + * Only when normalization is used: use scale factor from previous run, * prevents curves from jumping all over the place when tweaking them. */ ANIM_UNITCONV_NORMALIZE_FREEZE = (1 << 6), @@ -953,10 +958,11 @@ float ANIM_unit_mapping_get_factor( */ #define BEZKEYTYPE(bezt) ((bezt)->hide) -/* set/clear/toggle macro - * - channel - channel with a 'flag' member that we're setting - * - smode - 0=clear, 1=set, 2=invert - * - sflag - bitflag to set +/** + * Set/Clear/Toggle macro. + * \param channel: Channel with a 'flag' member that we're setting. + * \param smode: 0=clear, 1=set, 2=invert. + * \param sflag: bit-flag to set. */ #define ACHANNEL_SET_FLAG(channel, smode, sflag) \ { \ @@ -972,10 +978,11 @@ float ANIM_unit_mapping_get_factor( } \ ((void)0) -/* set/clear/toggle macro, where the flag is negative - * - channel - channel with a 'flag' member that we're setting - * - smode - 0=clear, 1=set, 2=invert - * - sflag - bitflag to set +/** + * Set/Clear/Toggle macro, where the flag is negative. + * \param channel: channel with a 'flag' member that we're setting. + * \param smode: 0=clear, 1=set, 2=invert. + * \param sflag: Bit-flag to set. */ #define ACHANNEL_SET_FLAG_NEG(channel, smode, sflag) \ { \ @@ -1067,13 +1074,13 @@ void ED_drivers_editor_init(struct bContext *C, struct ScrArea *area); /* ************************************************ */ typedef enum eAnimvizCalcRange { - /* Update motion paths at the current frame only. */ + /** Update motion paths at the current frame only. */ ANIMVIZ_CALC_RANGE_CURRENT_FRAME, - /* Try to limit updates to a close neighborhood of the current frame. */ + /** Try to limit updates to a close neighborhood of the current frame. */ ANIMVIZ_CALC_RANGE_CHANGED, - /* Update an entire range of the motion paths. */ + /** Update an entire range of the motion paths. */ ANIMVIZ_CALC_RANGE_FULL, } eAnimvizCalcRange; -- cgit v1.2.3