From 565faadd8ef6bb44d04ac3ff4e8438d21da3383e Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Mon, 1 Jun 2015 14:56:07 +1000 Subject: Cleanup: doxygen comments --- source/blender/windowmanager/intern/wm_cursors.c | 23 ++++---- .../blender/windowmanager/intern/wm_event_system.c | 62 ++++++++++++++-------- source/blender/windowmanager/intern/wm_jobs.c | 19 ++++--- source/blender/windowmanager/intern/wm_operators.c | 41 ++++++++------ source/blender/windowmanager/intern/wm_subwindow.c | 11 ++-- source/blender/windowmanager/intern/wm_window.c | 6 +-- 6 files changed, 97 insertions(+), 65 deletions(-) (limited to 'source/blender/windowmanager') diff --git a/source/blender/windowmanager/intern/wm_cursors.c b/source/blender/windowmanager/intern/wm_cursors.c index 68fd32cb450..d84b65847ca 100644 --- a/source/blender/windowmanager/intern/wm_cursors.c +++ b/source/blender/windowmanager/intern/wm_cursors.c @@ -313,21 +313,22 @@ void WM_cursor_time(wmWindow *win, int nr) } -/* ****************************************************************** - * Custom Cursor Description: +/** + * Custom Cursor Description + * ========================= * * Each bit represents a pixel, so 1 byte = 8 pixels, * the bytes go Left to Right. Top to bottom * the bits in a byte go right to left * (ie; 0x01, 0x80 represents a line of 16 pix with the first and last pix set.) * - * A 0 in the bitmap = bg_color, a 1 fg_color - * a 0 in the mask = transparent pix. + * - A 0 in the bitmap = bg_color, a 1 fg_color + * - a 0 in the mask = transparent pix. * * Until 32x32 cursors are supported on all platforms, the size of the * small cursors MUST be 16x16. * - * Large cursors have a MAXSIZE of 32x32. + * Large cursors have a maximum size of 32x32. * * Other than that, the specified size of the cursors is just a guideline, * However, the char array that defines the BM and MASK must be byte aligned. @@ -335,18 +336,20 @@ void WM_cursor_time(wmWindow *win, int nr) * (3 bytes = 17 bits rounded up to nearest whole byte). Pad extra bits * in mask with 0's. * - * Setting big_bm = NULL disables the large version of the cursor. + * Setting `big_bm = NULL` disables the large version of the cursor. * - * ******************************************************************* + * ---- * * There is a nice Python GUI utility that can be used for drawing cursors in * this format in the Blender source distribution, in - * blender/source/tools/MakeCursor.py . Start it with $ python MakeCursor.py - * It will copy its output to the console when you press 'Do it'. + * `./source/tools/utils/make_cursor_gui.py` . * + * Start it with the command `python3 make_cursor_gui.py` + * It will copy its output to the console when you press 'Do it'. */ -/* Because defining a cursor mixes declarations and executable code +/** + * Because defining a cursor mixes declarations and executable code * each cursor needs it's own scoping block or it would be split up * over several hundred lines of code. To enforce/document this better * I define 2 pretty brain-dead macros so it's obvious what the extra "[]" diff --git a/source/blender/windowmanager/intern/wm_event_system.c b/source/blender/windowmanager/intern/wm_event_system.c index 3a213cd4e2c..9505b060af7 100644 --- a/source/blender/windowmanager/intern/wm_event_system.c +++ b/source/blender/windowmanager/intern/wm_event_system.c @@ -702,7 +702,8 @@ static void wm_operator_reports(bContext *C, wmOperator *op, int retval, bool ca wm_add_reports(C, op->reports); } -/* this function is mainly to check that the rules for freeing +/** + * This function is mainly to check that the rules for freeing * an operator are kept in sync. */ static bool wm_operator_register_check(wmWindowManager *wm, wmOperatorType *ot) @@ -821,23 +822,29 @@ int WM_operator_call(bContext *C, wmOperator *op) return WM_operator_call_ex(C, op, false); } -/* this is intended to be used when an invoke operator wants to call exec on its self +/** + * This is intended to be used when an invoke operator wants to call exec on its self * and is basically like running op->type->exec() directly, no poll checks no freeing, - * since we assume whoever called invoke will take care of that */ + * since we assume whoever called invoke will take care of that + */ int WM_operator_call_notest(bContext *C, wmOperator *op) { return wm_operator_exec_notest(C, op); } -/* do this operator again, put here so it can share above code */ +/** + * Execute this operator again, put here so it can share above code + */ int WM_operator_repeat(bContext *C, wmOperator *op) { return wm_operator_exec(C, op, true, true); } -/* true if WM_operator_repeat can run +/** + * \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. */ + * 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. + */ bool WM_operator_repeat_check(const bContext *UNUSED(C), wmOperator *op) { if (op->type->exec != NULL) { @@ -1043,8 +1050,9 @@ bool WM_operator_last_properties_store(wmOperator *UNUSED(op)) #endif -static int wm_operator_invoke(bContext *C, wmOperatorType *ot, wmEvent *event, - PointerRNA *properties, ReportList *reports, const bool poll_only) +static int wm_operator_invoke( + bContext *C, wmOperatorType *ot, wmEvent *event, + PointerRNA *properties, ReportList *reports, const bool poll_only) { int retval = OPERATOR_PASS_THROUGH; @@ -1179,12 +1187,15 @@ static int wm_operator_invoke(bContext *C, wmOperatorType *ot, wmEvent *event, return retval; } -/* WM_operator_name_call is the main accessor function +/** + * #WM_operator_name_call is the main accessor function * this is for python to access since its done the operator lookup * - * invokes operator in context */ -static int wm_operator_call_internal(bContext *C, wmOperatorType *ot, PointerRNA *properties, ReportList *reports, - const short context, const bool poll_only) + * invokes operator in context + */ +static int wm_operator_call_internal( + bContext *C, wmOperatorType *ot, PointerRNA *properties, ReportList *reports, + const short context, const bool poll_only) { wmEvent *event; @@ -1324,13 +1335,16 @@ int WM_operator_name_call(bContext *C, const char *opstring, short context, Poin return 0; } -/* Similar to WM_operator_name_call called with WM_OP_EXEC_DEFAULT context. - * - wmOperatorType is used instead of operator name since python already has the operator type - * - poll() must be called by python before this runs. - * - reports can be passed to this function (so python can report them as exceptions) +/** + * Similar to #WM_operator_name_call called with #WM_OP_EXEC_DEFAULT context. + * + * - #wmOperatorType is used instead of operator name since python already has the operator type. + * - `poll()` must be called by python before this runs. + * - reports can be passed to this function (so python can report them as exceptions). */ -int WM_operator_call_py(bContext *C, wmOperatorType *ot, short context, - PointerRNA *properties, ReportList *reports, const bool is_undo) +int WM_operator_call_py( + bContext *C, wmOperatorType *ot, short context, + PointerRNA *properties, ReportList *reports, const bool is_undo) { int retval = OPERATOR_CANCELLED; @@ -1573,7 +1587,8 @@ static void wm_event_modalkeymap(const bContext *C, wmOperator *op, wmEvent *eve } } -/* Check whether operator is allowed to run in case interface is locked, +/** + * Check whether operator is allowed to run in case interface is locked, * If interface is unlocked, will always return truth. */ static bool wm_operator_check_locked_interface(bContext *C, wmOperatorType *ot) @@ -2511,11 +2526,12 @@ void WM_event_fileselect_event(wmWindowManager *wm, void *ophandle, int eventval /* operator is supposed to have a filled "path" property */ /* optional property: filetype (XXX enum?) */ -/* Idea is to keep a handler alive on window queue, owning the operator. +/** + * The idea here is to keep a handler alive on window queue, owning the operator. * The filewindow can send event to make it execute, thus ensuring * executing happens outside of lower level queues, with UI refreshed. - * Should also allow multiwin solutions */ - + * Should also allow multiwin solutions + */ void WM_event_add_fileselect(bContext *C, wmOperator *op) { wmEventHandler *handler, *handlernext; diff --git a/source/blender/windowmanager/intern/wm_jobs.c b/source/blender/windowmanager/intern/wm_jobs.c index 6bc858e861a..f8258d18c1a 100644 --- a/source/blender/windowmanager/intern/wm_jobs.c +++ b/source/blender/windowmanager/intern/wm_jobs.c @@ -157,8 +157,8 @@ static void wm_job_main_thread_yield(wmJob *wm_job, bool ending) BLI_ticket_mutex_lock(wm_job->main_thread_mutex); } -/* finds: - * if type or owner, compare for it, otherwise any matching job +/** + * Finds if type or owner, compare for it, otherwise any matching job. */ static wmJob *wm_job_find(wmWindowManager *wm, void *owner, const int job_type) { @@ -185,9 +185,12 @@ static wmJob *wm_job_find(wmWindowManager *wm, void *owner, const int job_type) /* ******************* public API ***************** */ -/* returns current or adds new job, but doesnt run it */ -/* every owner only gets a single job, adding a new one will stop running job and - * when stopped it starts the new one */ +/** + * \return current job or adds new job, but doesnt run it. + * + * \note every owner only gets a single job, + * adding a new one will stop running job and when stopped it starts the new one. + */ wmJob *WM_jobs_get(wmWindowManager *wm, wmWindow *win, void *owner, const char *name, int flag, int job_type) { wmJob *wm_job = wm_job_find(wm, owner, job_type); @@ -375,8 +378,10 @@ static void wm_jobs_test_suspend_stop(wmWindowManager *wm, wmJob *test) // if (suspend) printf("job suspended: %s\n", test->name); } -/* if job running, the same owner gave it a new job */ -/* if different owner starts existing startjob, it suspends itself */ +/** + * if job running, the same owner gave it a new job. + * if different owner starts existing startjob, it suspends itself + */ void WM_jobs_start(wmWindowManager *wm, wmJob *wm_job) { if (wm_job->running) { diff --git a/source/blender/windowmanager/intern/wm_operators.c b/source/blender/windowmanager/intern/wm_operators.c index 1ab1ac8a28d..3c23f7367fb 100644 --- a/source/blender/windowmanager/intern/wm_operators.c +++ b/source/blender/windowmanager/intern/wm_operators.c @@ -577,12 +577,13 @@ void WM_operator_bl_idname(char *to, const char *from) to[0] = 0; } -/* Print a string representation of the operator, with the args that it runs so python can run it again. +/** + * Print a string representation of the operator, with the args that it runs so python can run it again. * * When calling from an existing wmOperator, better to use simple version: - * WM_operator_pystring(C, op); + * `WM_operator_pystring(C, op);` * - * Note: both op and opptr may be NULL (op is only used for macro operators). + * \note Both \a op and \a opptr may be `NULL` (\a op is only used for macro operators). */ char *WM_operator_pystring_ex(bContext *C, wmOperator *op, const bool all_args, const bool macro_args, wmOperatorType *ot, PointerRNA *opptr) @@ -1722,18 +1723,20 @@ static int wm_operator_props_popup_ex(bContext *C, wmOperator *op, return OPERATOR_RUNNING_MODAL; } -/* Same as WM_operator_props_popup but don't use operator redo. - * just wraps WM_operator_props_dialog_popup. +/** + * Same as #WM_operator_props_popup but don't use operator redo. + * just wraps #WM_operator_props_dialog_popup. */ int WM_operator_props_popup_confirm(bContext *C, wmOperator *op, const wmEvent *UNUSED(event)) { return wm_operator_props_popup_ex(C, op, false, false); } -/* Same as WM_operator_props_popup but call the operator first, +/** + * Same as #WM_operator_props_popup but call the operator first, * This way - the button values correspond to the result of the operator. - * Without this, first access to a button will make the result jump, - * see [#32452] */ + * Without this, first access to a button will make the result jump, see T32452. + */ int WM_operator_props_popup_call(bContext *C, wmOperator *op, const wmEvent *UNUSED(event)) { return wm_operator_props_popup_ex(C, op, true, true); @@ -3166,9 +3169,10 @@ void WM_paint_cursor_end(wmWindowManager *wm, void *handle) /* **************** Border gesture *************** */ -/* Border gesture has two types: - * 1) WM_GESTURE_CROSS_RECT: starts a cross, on mouse click it changes to border - * 2) WM_GESTURE_RECT: starts immediate as a border, on mouse click or release it ends +/** + * Border gesture has two types: + * -# #WM_GESTURE_CROSS_RECT: starts a cross, on mouse click it changes to border. + * -# #WM_GESTURE_RECT: starts immediate as a border, on mouse click or release it ends. * * It stores 4 values (xmin, xmax, ymin, ymax) and event it ended with (event_type) */ @@ -4107,12 +4111,15 @@ typedef enum { RC_PROP_REQUIRE_BOOL = 4, } RCPropFlags; -/* attempt to retrieve the rna pointer/property from an rna path; - * returns 0 for failure, 1 for success, and also 1 if property is not - * set */ -static int radial_control_get_path(PointerRNA *ctx_ptr, wmOperator *op, - const char *name, PointerRNA *r_ptr, - PropertyRNA **r_prop, int req_length, RCPropFlags flags) +/** + * Attempt to retrieve the rna pointer/property from an rna path. + * + * \return 0 for failure, 1 for success, and also 1 if property is not set. + */ +static int radial_control_get_path( + PointerRNA *ctx_ptr, wmOperator *op, + const char *name, PointerRNA *r_ptr, + PropertyRNA **r_prop, int req_length, RCPropFlags flags) { PropertyRNA *unused_prop; int len; diff --git a/source/blender/windowmanager/intern/wm_subwindow.c b/source/blender/windowmanager/intern/wm_subwindow.c index 4ce2415e310..d081644fa61 100644 --- a/source/blender/windowmanager/intern/wm_subwindow.c +++ b/source/blender/windowmanager/intern/wm_subwindow.c @@ -54,11 +54,12 @@ #include "WM_api.h" #include "wm_subwindow.h" -/* wmSubWindow stored in wmWindow... but not exposed outside this C file */ -/* it seems a bit redundant (area regions can store it too, but we keep it - * because we can store all kind of future opengl fanciness here */ - -/* we use indices and array because: +/** + * \note #wmSubWindow stored in #wmWindow but not exposed outside this C file, + * it seems a bit redundant (area regions can store it too, but we keep it + * because we can store all kind of future opengl fanciness here. + * + * We use indices and array because: * - index has safety, no pointers from this C file hanging around * - fast lookups of indices with array, list would give overhead * - old code used it this way... diff --git a/source/blender/windowmanager/intern/wm_window.c b/source/blender/windowmanager/intern/wm_window.c index 6d1bf51902c..f704e985f8f 100644 --- a/source/blender/windowmanager/intern/wm_window.c +++ b/source/blender/windowmanager/intern/wm_window.c @@ -1117,10 +1117,10 @@ static int ghost_event_proc(GHOST_EventHandle evt, GHOST_TUserDataPtr C_void_ptr } -/* This timer system only gives maximum 1 timer event per redraw cycle, +/** + * This timer system only gives maximum 1 timer event per redraw cycle, * to prevent queues to get overloaded. - * Timer handlers should check for delta to decide if they just - * update, or follow real time. + * Timer handlers should check for delta to decide if they just update, or follow real time. * Timer handlers can also set duration to match frames passed */ static int wm_window_timer(const bContext *C) -- cgit v1.2.3