From cf49cbde453cf5b92a6da00d03c18fa7149116cb Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 26 Jul 2023 15:23:24 +1000 Subject: [PATCH] Cleanup: use doxygen formatting in UI_interface.h, DNA_screen_types.h Also use doxygen type references & correct some typos. --- source/blender/editors/include/UI_interface.h | 113 ++++++++++-------- source/blender/makesdna/DNA_screen_types.h | 79 +++++++----- 2 files changed, 111 insertions(+), 81 deletions(-) diff --git a/source/blender/editors/include/UI_interface.h b/source/blender/editors/include/UI_interface.h index 76264d552da..5074d1f179f 100644 --- a/source/blender/editors/include/UI_interface.h +++ b/source/blender/editors/include/UI_interface.h @@ -96,8 +96,10 @@ typedef struct uiViewItemHandle uiViewItemHandle; */ #define UI_VALUE_INDETERMINATE_CHAR BLI_STR_UTF8_EM_DASH -/* Separator for text in search menus (right pointing arrow). - * keep in sync with `string_search.cc`. */ +/** + * Separator for text in search menus (right pointing arrow). + * keep in sync with `string_search.cc`. + */ #define UI_MENU_ARROW_SEP BLI_STR_UTF8_BLACK_RIGHT_POINTING_SMALL_TRIANGLE /* names */ @@ -113,7 +115,7 @@ typedef struct uiViewItemHandle uiViewItemHandle; */ #define UI_REGION_OVERLAP_MARGIN (U.widget_unit / 3) -/* use for clamping popups within the screen */ +/** Use for clamping popups within the screen. */ #define UI_SCREEN_MARGIN 10 /** #uiBlock.emboss and #uiBut.emboss */ @@ -131,7 +133,7 @@ typedef enum eUIEmbossType { UI_EMBOSS_UNDEFINED = 255, /* For layout engine, use emboss from block. */ } eUIEmbossType; -/* uiBlock->direction */ +/** #uiBlock::direction */ enum { UI_DIR_UP = 1 << 0, UI_DIR_DOWN = 1 << 1, @@ -161,10 +163,10 @@ enum { UI_BLOCK_OUT_1 = 1 << 10, UI_BLOCK_SEARCH_MENU = 1 << 11, UI_BLOCK_POPUP_MEMORY = 1 << 12, - /* Stop handling mouse events. */ + /** Stop handling mouse events. */ UI_BLOCK_CLIP_EVENTS = 1 << 13, - /* block->flag bits 14-17 are identical to but->drawflag bits */ + /* #uiBlock::flags bits 14-17 are identical to #uiBut::drawflag bits. */ UI_BLOCK_POPUP_HOLD = 1 << 18, UI_BLOCK_LIST_ITEM = 1 << 19, @@ -201,6 +203,7 @@ enum { /** #uiBut.flag general state flags. */ enum { /* WARNING: the first 8 flags are internal (see #UI_SELECT definition). */ + UI_BUT_ICON_SUBMENU = 1 << 8, UI_BUT_ICON_PREVIEW = 1 << 9, @@ -262,10 +265,10 @@ enum { UI_BUT_DRAGPOIN_FREE = (1 << 1), }; -/* Default font size for normal text. */ +/** Default font size for normal text. */ #define UI_DEFAULT_TEXT_POINTS 11.0f -/* Larger size used for title text. */ +/** Larger size used for title text. */ #define UI_DEFAULT_TITLE_POINTS 11.0f #define UI_PANEL_WIDTH 340 @@ -274,11 +277,11 @@ enum { #define UI_NAVIGATION_REGION_WIDTH UI_COMPACT_PANEL_WIDTH #define UI_NARROW_NAVIGATION_REGION_WIDTH 100 -/* The width of one icon column of the Toolbar. */ +/** The width of one icon column of the Toolbar. */ #define UI_TOOLBAR_COLUMN (1.25f * ICON_DEFAULT_HEIGHT_TOOLBAR) -/* The space between the Toolbar and the area's edge. */ +/** The space between the Toolbar and the area's edge. */ #define UI_TOOLBAR_MARGIN (0.5f * ICON_DEFAULT_HEIGHT_TOOLBAR) -/* Total width of Toolbar showing one icon column. */ +/** Total width of Toolbar showing one icon column. */ #define UI_TOOLBAR_WIDTH UI_TOOLBAR_MARGIN + UI_TOOLBAR_COLUMN #define UI_PANEL_CATEGORY_MARGIN_WIDTH (U.widget_unit * 1.0f) @@ -288,19 +291,23 @@ enum { #define UI_PANEL_MARGIN_X (U.widget_unit * 0.4f) #define UI_PANEL_MARGIN_Y (U.widget_unit * 0.1f) -/* but->drawflag - these flags should only affect how the button is drawn. */ -/* NOTE: currently, these flags *are not passed* to the widget's state() or draw() functions - * (except for the 'align' ones)! +/** + * #uiBut::drawflag, these flags should only affect how the button is drawn. + * + * \note currently, these flags *are not passed* to the widgets state() or draw() functions + * (except for the 'align' ones)! */ enum { /** Text and icon alignment (by default, they are centered). */ UI_BUT_TEXT_LEFT = 1 << 1, UI_BUT_ICON_LEFT = 1 << 2, UI_BUT_TEXT_RIGHT = 1 << 3, - /** Prevent the button to show any tooltip. */ + /** Prevent the button to show any tool-tip. */ UI_BUT_NO_TOOLTIP = 1 << 4, - /** Show a quick tooltip label, that is, a short tooltip that appears faster than the full one - * and only shows the label. After a short delay the full toolitp is shown if any. */ + /** + * Show a quick tool-tip label, that is, a short tool-tip that appears faster than the full one + * and only shows the label. After a short delay the full tool-tip is shown if any. + */ UI_BUT_HAS_TOOLTIP_LABEL = 1 << 5, /** Do not add the usual horizontal padding for text drawing. */ UI_BUT_NO_TEXT_PADDING = 1 << 6, @@ -318,7 +325,8 @@ enum { * Warning - HACK! * Needed for buttons which are not TOP/LEFT aligned, * but have some top/left corner stitched to some other TOP/LEFT-aligned button, - * because of 'corrective' hack in widget_roundbox_set()... */ + * because of "corrective" hack in #widget_roundbox_set(). + */ UI_BUT_ALIGN_STITCH_TOP = 1 << 18, UI_BUT_ALIGN_STITCH_LEFT = 1 << 19, UI_BUT_ALIGN_ALL = UI_BUT_ALIGN | UI_BUT_ALIGN_STITCH_TOP | UI_BUT_ALIGN_STITCH_LEFT, @@ -337,10 +345,10 @@ enum { /** Value is animated, but the current value differs from the animated one. */ UI_BUT_ANIMATED_CHANGED = 1 << 24, - /* Draw the checkbox buttons inverted. */ + /** Draw the checkbox buttons inverted. */ UI_BUT_CHECKBOX_INVERT = 1 << 25, - /* Drawn in a way that indicates that the state/value is unknown. */ + /** Drawn in a way that indicates that the state/value is unknown. */ UI_BUT_INDETERMINATE = 1 << 26, }; @@ -362,10 +370,13 @@ typedef enum { UI_BUT_POIN_BIT = 256, /* OR'd with a bit index. */ } eButPointerType; -/* requires (but->poin != NULL) */ +/** \note requires `but->poin != NULL`. */ #define UI_BUT_POIN_TYPES (UI_BUT_POIN_FLOAT | UI_BUT_POIN_SHORT | UI_BUT_POIN_CHAR) -/* assigned to but->type, OR'd with the flags above when passing args */ +/** + * #uiBut::type + * OR'd with #eButPointerType when passing as an argument. + */ typedef enum { UI_BTYPE_BUT = 1 << 9, UI_BTYPE_ROW = 2 << 9, @@ -429,7 +440,7 @@ typedef enum { /** Resize handle (resize UI-list). */ UI_BTYPE_GRIP = 57 << 9, UI_BTYPE_DECORATOR = 58 << 9, - /* An item a view (see #ui::AbstractViewItem). */ + /** An item a view (see #ui::AbstractViewItem). */ UI_BTYPE_VIEW_ITEM = 59 << 9, } eButType; @@ -512,10 +523,10 @@ void UI_draw_widget_scroll(struct uiWidgetColors *wcol, * \note in case this middle clipping would just remove a few chars, * it rather clips right, which is more readable. * - * If rpart_sep is not Null, the part of str starting to first occurrence of rpart_sep + * If `rpart_sep` is not null, the part of `str` starting to first occurrence of `rpart_sep` * is preserved at all cost. * Useful for strings with shortcuts - * (like 'AVeryLongFooBarLabelForMenuEntry|Ctrl O' -> 'AVeryLong...MenuEntry|Ctrl O'). + * (like `A Very Long Foo Bar Label For Menu Entry|Ctrl O' -> 'AVeryLong...MenuEntry|Ctrl O`). */ float UI_text_clip_middle_ex(const struct uiFontStyle *fstyle, char *str, @@ -525,9 +536,9 @@ float UI_text_clip_middle_ex(const struct uiFontStyle *fstyle, char rpart_sep); /** - * Callbacks + * Callbacks. * - * UI_block_func_handle_set/ButmFunc are for handling events through a callback. + * #UI_block_func_handle_set/ButmFunc are for handling events through a callback. * HandleFunc gets the retval passed on, and ButmFunc gets a2. The latter is * mostly for compatibility with older code. * @@ -574,7 +585,7 @@ typedef struct ARegion *(*uiButSearchTooltipFn)(struct bContext *C, void *active); typedef void (*uiButSearchListenFn)(const struct wmRegionListenerParams *params, void *arg); -/* Must return allocated string. */ +/** Must return an allocated string. */ typedef char *(*uiButToolTipFunc)(struct bContext *C, void *argN, const char *tip); typedef void (*uiBlockHandleFunc)(struct bContext *C, void *arg, int event); @@ -851,7 +862,7 @@ void UI_block_lock_clear(uiBlock *block); void UI_block_align_begin(uiBlock *block); void UI_block_align_end(uiBlock *block); -/* block bounds/position calculation */ +/** Block bounds/position calculation. */ typedef enum { UI_BLOCK_BOUNDS_NONE = 0, UI_BLOCK_BOUNDS = 1, @@ -1279,7 +1290,7 @@ uiBut *uiDefIconButO_ptr(uiBlock *block, uiBut *uiDefButImage( uiBlock *block, void *imbuf, int x, int y, short width, short height, const uchar color[4]); uiBut *uiDefButAlert(uiBlock *block, int icon, int x, int y, short width, short height); -/* Button containing both string label and icon */ +/** Button containing both string label and icon. */ uiBut *uiDefIconTextBut(uiBlock *block, int type, int retval, @@ -1382,7 +1393,7 @@ uiBut *uiDefIconTextButO_ptr(uiBlock *block, short height, const char *tip); -/* for passing inputs to ButO buttons */ +/** For passing inputs to ButO buttons. */ struct PointerRNA *UI_but_operator_ptr_get(uiBut *but); void UI_but_context_ptr_set(uiBlock *block, @@ -1421,9 +1432,11 @@ typedef struct uiStringInfo { char *strinfo; } uiStringInfo; -/* NOTE: Expects pointers to uiStringInfo structs as parameters. - * Will fill them with translated strings, when possible. - * Strings in uiStringInfo must be MEM_freeN'ed by caller. */ +/** + * \note Expects pointers to #uiStringInfo structs as parameters. + * Will fill them with translated strings, when possible. + * Strings in #uiStringInfo must be MEM_freeN'ed by caller. + */ void UI_but_string_info_get(struct bContext *C, uiBut *but, ...) ATTR_SENTINEL(0); void UI_but_extra_icon_string_info_get(struct bContext *C, uiButExtraOpIcon *extra_icon, ...) ATTR_SENTINEL(0); @@ -1605,21 +1618,21 @@ uiBut *uiDefSearchButO_ptr(uiBlock *block, float a2, const char *tip); -/* For uiDefAutoButsRNA */ +/** For #uiDefAutoButsRNA. */ typedef enum { - /* Keep current layout for aligning label with property button. */ + /** Keep current layout for aligning label with property button. */ UI_BUT_LABEL_ALIGN_NONE, - /* Align label and property button vertically. */ + /** Align label and property button vertically. */ UI_BUT_LABEL_ALIGN_COLUMN, - /* Split layout into a column for the label and one for property button. */ + /** Split layout into a column for the label and one for property button. */ UI_BUT_LABEL_ALIGN_SPLIT_COLUMN, } eButLabelAlign; -/* Return info for uiDefAutoButsRNA */ +/** Return info for uiDefAutoButsRNA. */ typedef enum eAutoPropButsReturn { - /* Returns when no buttons were added */ + /** Returns when no buttons were added */ UI_PROP_BUTS_NONE_ADDED = 1 << 0, - /* Returned when any property failed the custom check callback (check_prop) */ + /** Returned when any property failed the custom check callback (check_prop) */ UI_PROP_BUTS_ANY_FAILED_CHECK = 1 << 1, } eAutoPropButsReturn; @@ -2538,13 +2551,13 @@ void uiTemplateCacheFileLayers(uiLayout *layout, const struct bContext *C, struct PointerRNA *fileptr); -/* Default UIList class name, keep in sync with its declaration in bl_ui/__init__.py */ +/** Default UIList class name, keep in sync with its declaration in `bl_ui/__init__.py`. */ #define UI_UL_DEFAULT_CLASS_NAME "UI_UL_list" enum uiTemplateListFlags { UI_TEMPLATE_LIST_FLAG_NONE = 0, UI_TEMPLATE_LIST_SORT_REVERSE = (1 << 0), UI_TEMPLATE_LIST_SORT_LOCK = (1 << 1), - /* Don't allow resizing the list, i.e. don't add the grip button. */ + /** Don't allow resizing the list, i.e. don't add the grip button. */ UI_TEMPLATE_LIST_NO_GRIP = (1 << 2), /** Do not show filtering options, not even the button to expand/collapse them. Also hides the * grip button. */ @@ -3157,10 +3170,14 @@ int UI_fontstyle_height_max(const struct uiFontStyle *fs); */ void UI_draw_icon_tri(float x, float y, char dir, const float[4]); -/* XXX: read a style configure */ +/** + * Read a style (without any scaling applied). + */ const struct uiStyle *UI_style_get(void); /* use for fonts etc */ -/* for drawing, scaled with DPI setting */ -const struct uiStyle *UI_style_get_dpi(void); /* DPI scaled settings for drawing */ +/** + * Read a style (with the current DPI applied). + */ +const struct uiStyle *UI_style_get_dpi(void); /* linker workaround ack! */ void UI_template_fix_linking(void); @@ -3301,10 +3318,10 @@ void UI_style_init_default(void); void UI_interface_tag_script_reload(void); -/* Special drawing for toolbar, mainly workarounds for inflexible icon sizing. */ +/** Special drawing for toolbar, mainly workarounds for inflexible icon sizing. */ #define USE_UI_TOOLBAR_HACK -/* Support click-drag motion which presses the button and closes a popover (like a menu). */ +/** Support click-drag motion which presses the button and closes a popover (like a menu). */ #define USE_UI_POPOVER_ONCE /** diff --git a/source/blender/makesdna/DNA_screen_types.h b/source/blender/makesdna/DNA_screen_types.h index 023e502cd51..cef47df1653 100644 --- a/source/blender/makesdna/DNA_screen_types.h +++ b/source/blender/makesdna/DNA_screen_types.h @@ -305,10 +305,10 @@ typedef struct uiList { /* some list UI data need to be saved in file */ int filter_flag; int filter_sort_flag; - /* Custom sub-classes properties. */ + /** Custom sub-classes properties. */ IDProperty *properties; - /* Dynamic data (runtime). */ + /** Dynamic data (runtime). */ uiListDyn *dyn_data; } uiList; @@ -331,13 +331,16 @@ typedef struct uiPreview { } uiPreview; typedef struct ScrGlobalAreaData { - /* Global areas have a non-dynamic size. That means, changing the window - * size doesn't affect their size at all. However, they can still be - * 'collapsed', by changing this value. Ignores DPI (ED_area_global_size_y - * and winx/winy don't) */ + /** + * Global areas have a non-dynamic size. That means, changing the window size doesn't + * affect their size at all. However, they can still be 'collapsed', by changing this value. + * Ignores DPI (#ED_area_global_size_y and winx/winy don't). + */ short cur_fixed_height; - /* For global areas, this is the min and max size they can use depending on - * if they are 'collapsed' or not. */ + /** + * For global areas, this is the min and max size they can use depending on + * if they are 'collapsed' or not. + */ short size_min, size_max; /** GlobalAreaAlign. */ short align; @@ -405,19 +408,21 @@ typedef struct ScrArea { /** Callbacks for this space type. */ struct SpaceType *type; - /* Non-NULL if this area is global. */ + /** Non-NULL if this area is global. */ ScrGlobalAreaData *global; - /* A list of space links (editors) that were open in this area before. When + /** + * #SpaceLink. + * A list of space links (editors) that were open in this area before. When * changing the editor type, we try to reuse old editor data from this list. * The first item is the active/visible one. */ - /** #SpaceLink. */ ListBase spacedata; - /* NOTE: This region list is the one from the active/visible editor (first item in + /** + * #ARegion. + * \note This region list is the one from the active/visible editor (first item in * spacedata list). Use SpaceLink.regionbase if it's inactive (but only then)! */ - /** #ARegion. */ ListBase regionbase; /** #wmEventHandler. */ ListBase handlers; @@ -429,7 +434,7 @@ typedef struct ScrArea { } ScrArea; typedef struct ARegion_Runtime { - /* Panel category to use between 'layout' and 'draw'. */ + /** Panel category to use between 'layout' and 'draw'. */ const char *category; /** @@ -442,7 +447,7 @@ typedef struct ARegion_Runtime { /* The offset needed to not overlap with window scroll-bars. Only used by HUD regions for now. */ int offset_x, offset_y; - /* Maps uiBlock->name to uiBlock for faster lookups. */ + /** Maps #uiBlock::name to uiBlock for faster lookups. */ struct GHash *block_name_map; } ARegion_Runtime; @@ -457,8 +462,10 @@ typedef struct ARegion { rcti drawrct; /** Size. */ short winx, winy; - /* This is a Y offset on the panel tabs that represents pixels, where zero represents no scroll - - * the first category always shows first at the top. */ + /** + * This is a Y offset on the panel tabs that represents pixels, + * where zero represents no scroll - the first category always shows first at the top. + */ int category_scroll; char _pad0[4]; @@ -558,8 +565,10 @@ enum { /** #bScreen.state */ enum { SCREENNORMAL = 0, - SCREENMAXIMIZED = 1, /* one editor taking over the screen */ - SCREENFULL = 2, /* one editor taking over the screen with no bare-minimum UI elements */ + /** One editor taking over the screen. */ + SCREENMAXIMIZED = 1, + /** One editor taking over the screen with no bare-minimum UI elements. */ + SCREENFULL = 2, }; /** #bScreen.redraws_flag */ @@ -592,7 +601,7 @@ enum { PNL_INSTANCED_LIST_ORDER_CHANGED = (1 << 7), }; -/* Fallback panel category (only for old scripts which need updating) */ +/** Fallback panel category (only for old scripts which need updating). */ #define PNL_CATEGORY_FALLBACK "Misc" /** #uiList.layout_type */ @@ -605,11 +614,11 @@ enum { /** #uiList.flag */ enum { - /* Scroll list to make active item visible. */ + /** Scroll list to make active item visible. */ UILST_SCROLL_TO_ACTIVE_ITEM = 1 << 0, }; -/* Value (in number of items) we have to go below minimum shown items to enable auto size. */ +/** Value (in number of items) we have to go below minimum shown items to enable auto size. */ #define UI_LIST_AUTO_SIZE_THRESHOLD 1 /* uiList filter flags (dyn_data) */ @@ -668,13 +677,13 @@ typedef enum eRegion_Type { #define RGN_TYPE_NUM (RGN_TYPE_XR + 1) } eRegion_Type; -/* use for function args */ +/** Use for function args. */ #define RGN_TYPE_ANY -1 -/* Region supports panel tabs (categories). */ +/** Region supports panel tabs (categories). */ #define RGN_TYPE_HAS_CATEGORY_MASK (1 << RGN_TYPE_UI) -/* Check for any kind of header region. */ +/** Check for any kind of header region. */ #define RGN_TYPE_IS_HEADER_ANY(regiontype) \ (((1 << (regiontype)) & \ ((1 << RGN_TYPE_HEADER) | 1 << (RGN_TYPE_TOOL_HEADER) | (1 << RGN_TYPE_FOOTER))) != 0) @@ -735,22 +744,26 @@ enum { /** #ARegion.do_draw */ enum { - /* Region must be fully redrawn. */ + /** Region must be fully redrawn. */ RGN_DRAW = 1, - /* Redraw only part of region, for sculpting and painting to get smoother - * stroke painting on heavy meshes. */ + /** + * Redraw only part of region, for sculpting and painting to get smoother + * stroke painting on heavy meshes. + */ RGN_DRAW_PARTIAL = 2, - /* For outliner, to do faster redraw without rebuilding outliner tree. + /** + * For outliner, to do faster redraw without rebuilding outliner tree. * For 3D viewport, to display a new progressive render sample without - * while other buffers and overlays remain unchanged. */ + * while other buffers and overlays remain unchanged. + */ RGN_DRAW_NO_REBUILD = 4, - /* Set while region is being drawn. */ + /** Set while region is being drawn. */ RGN_DRAWING = 8, - /* For popups, to refresh UI layout along with drawing. */ + /** For popups, to refresh UI layout along with drawing. */ RGN_REFRESH_UI = 16, - /* Only editor overlays (currently gizmos only!) should be redrawn. */ + /** Only editor overlays (currently gizmos only!) should be redrawn. */ RGN_DRAW_EDITOR_OVERLAYS = 32, };