archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

Cleanup: doxygen comments

Browse Source
This commit is contained in:
Campbell Barton
2015-06-01 14:56:07 +10:00
parent 668f1f9554
commit 565faadd8e
6 changed files with 97 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
source/blender/windowmanager/intern/wm_cursors.c
View File

@@ -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 "[]"

62
source/blender/windowmanager/intern/wm_event_system.c
View File

@@ -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;

19
source/blender/windowmanager/intern/wm_jobs.c
View File

@@ -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) {

41
source/blender/windowmanager/intern/wm_operators.c
View File

@@ -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;

11
source/blender/windowmanager/intern/wm_subwindow.c
View File

@@ -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...

6
source/blender/windowmanager/intern/wm_window.c
View File

@@ -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)