[Bf-blender-cvs] [565faad] master: Cleanup: doxygen comments
Campbell Barton
noreply at git.blender.org
Mon Jun 1 06:57:10 CEST 2015
Commit: 565faadd8ef6bb44d04ac3ff4e8438d21da3383e
Author: Campbell Barton
Date: Mon Jun 1 14:56:07 2015 +1000
Branches: master
https://developer.blender.org/rB565faadd8ef6bb44d04ac3ff4e8438d21da3383e
Cleanup: doxygen comments
===================================================================
M source/blender/windowmanager/intern/wm_cursors.c
M source/blender/windowmanager/intern/wm_event_system.c
M source/blender/windowmanager/intern/wm_jobs.c
M source/blender/windowmanager/intern/wm_operators.c
M source/blender/windowmanager/intern/wm_subwindow.c
M source/blender/windowmanager/intern/wm_window.c
===================================================================
diff --git a/source/blender/windowmanager/intern/wm_cursors.c b/source/blender/windowmanager/intern/wm_cursors.c
index 68fd32c..d84b658 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 3a213cd..9505b06 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 6bc858e..f8258d1 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 1ab1ac8..3c23f73 100644
--- a/source/blender/windowmanager/intern/wm_operators.c
+++ b/sourc
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list