GNOME.org
 

asyncworker r88 - in trunk: docs/reference/tmpl liboasyncworker

Author: pvanhoof
Date: Sun Apr 27 12:42:11 2008
New Revision: 88
URL: http://svn.gnome.org/viewvc/asyncworker?rev=88&view=rev

Log:
Better gtk-doc comments

Modified:
   trunk/docs/reference/tmpl/oasyncworker.sgml
   trunk/docs/reference/tmpl/oasyncworkertask.sgml
   trunk/liboasyncworker/oasyncworker.c
   trunk/liboasyncworker/oasyncworkertask.c

Modified: trunk/docs/reference/tmpl/oasyncworker.sgml
==============================================================================
--- trunk/docs/reference/tmpl/oasyncworker.sgml	(original)
+++ trunk/docs/reference/tmpl/oasyncworker.sgml	Sun Apr 27 12:42:11 2008
@@ -6,9 +6,7 @@
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The worker queue is the entity that will process your tasks. It will automatically launch a worker thread and will sort tasks 
-on priorty when a task gets added. It has support for cancellation of tasks. Note that the task that is to be cancelled needs to have
-cancellation points in its body. The cancellation will then happen at the first next such cancellation point.
+The worker queue processes your tasks. It automatically launches a worker thread and sorts tasks on priorty. It supports cancellation of tasks. Note that the task that is to be cancelled needs to have cancellation points in its body. The cancellation then happens at the first next such cancellation point.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->

Modified: trunk/docs/reference/tmpl/oasyncworkertask.sgml
==============================================================================
--- trunk/docs/reference/tmpl/oasyncworkertask.sgml	(original)
+++ trunk/docs/reference/tmpl/oasyncworkertask.sgml	Sun Apr 27 12:42:11 2008
@@ -6,12 +6,7 @@
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The task object is the instance of something that needs to be done by the worker queue. What it is that needs to
-be done, is typically a function (the body of the task). The system allows you to also define a callback in which 
-you can securely free resources that have been used by this task. In the body of a task you can set cancellation
-points. Such a cancellation point will be the location where the task cancels if another context (for example
-the userinterface) instructs a cancellation.
-
+The task needs to be done by the worker queue. What needs to be done, is a function (the body of the task). The system also allows to define a callback in which you can free resources. In the body of a task you can set cancellation points. Such a cancellation point will be the location where the task cancels if you request a cancellation.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->

Modified: trunk/liboasyncworker/oasyncworker.c
==============================================================================
--- trunk/liboasyncworker/oasyncworker.c	(original)
+++ trunk/liboasyncworker/oasyncworker.c	Sun Apr 27 12:42:11 2008
@@ -1,5 +1,5 @@
 /* OAsyncWorker
- * Copyright (C) 2005, 2007 Philip Van Hoof <pvanhoof gnome org>.
+ * Copyright (C) 2005 - 2008 Philip Van Hoof <pvanhoof gnome org>.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -165,13 +165,12 @@
  * OAsyncWorker::task-started
  * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got started
- * @user_data: user data set when the signal handler was connected.
  *
  * Emitted when a task starts
  *
- * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
- * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
- * Read http://live.gnome.org/GdkLock for more information.
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information.
  *
  * Since: 1.0
  **/
@@ -189,13 +188,12 @@
  * OAsyncWorker::task-cancelled
  * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got cancelled
- * @user_data: user data set when the signal handler was connected.
  *
  * Emitted when a task gets cancelled
  *
- * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
- * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
- * Read http://live.gnome.org/GdkLock for more information.
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information. The emission itself occurs in the #GMainLoop.
  *
  * Since: 1.0
  **/
@@ -213,14 +211,12 @@
  * OAsyncWorker::task-added
  * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got added
- * @user_data: user data set when the signal handler was connected.
  *
  * Emitted when a task gets added
  *
- * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
- * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
- * They are thrown to the #GMainLoop, however. Read http://live.gnome.org/GdkLock 
- * for more information.
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information. The emission itself occurs in the #GMainLoop.
  *
  * Since: 1.0
  **/
@@ -239,14 +235,12 @@
  * OAsyncWorker::task-finished
  * @self: the #OAsyncWorker on which the signal is emitted
  * @arg1: the task number that got started
- * @user_data: user data set when the signal handler was connected.
  *
  * Emitted when a task finishes
  *
- * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
- * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
- * They are thrown to the #GMainLoop, however. Read http://live.gnome.org/GdkLock
- * for more information.
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information. The emission itself occurs in the #GMainLoop.
  *
  * Since: 1.0
  **/
@@ -264,14 +258,12 @@
  * OAsyncWorker::task-removed
  * @self: the object on which the signal is emitted
  * @arg1: the task number that got started
- * @user_data: user data set when the signal handler was connected.
  *
  * Emitted when a task gets removed
  *
- * Signals in OAsyncWorker don't acquire the Gdk lock (in case you are planning
- * to use the Gdk or Gtk+ subsystems in your handlers, you must do this yourself).
- * They are thrown to the #GMainLoop, however. Read http://live.gnome.org/GdkLock 
- * for more information.
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information. The emission itself occurs in the #GMainLoop.
  *
  * Since: 1.0
  **/
@@ -353,7 +345,7 @@
 
 /**
  * o_async_worker_new:
- * @returns: a new queue
+ * @returns: a new worker queue
  *
  * Create a new worker
  * 
@@ -568,11 +560,26 @@
 /**
  * o_async_worker_add:
  * @queue: a #OAsyncWorker
- * @task: (callee-owns): the #OAsyncWorkerTask to add
+ * @task: the #OAsyncWorkerTask to add
  * @returns: the task_id
  *
  * Add a task to the queue
  *
+ * <informalexample><programlisting>
+ * #include <oasyncworker/oasyncworker.h>
+ * int main (int argc, char **argv) 
+ * {
+ *   OAsyncWorker *queue = o_async_worker_new ();
+ *   OAsyncWorkerTask *task = o_async_worker_task_new ();
+ *   o_async_worker_task_set_func (task, ...);
+ *   o_async_worker_task_set_callback (task, ...);
+ *   o_async_worker_add (queue, task);
+ *   g_object_unref (task)l
+ *   o_async_worker_join (queue);
+ *   g_object_unref (queue);
+ * }
+ * </programlisting></informalexample>
+ *
  * Since: 1.0
  **/
 gint
@@ -620,14 +627,18 @@
  * o_async_worker_remove:
  * @queue: a #OAsyncWorker
  * @task_id: the id of the task to remove
- * @run_callback: whether to still run the callback function
+ * @run_callback: whether or not still to run the callback function
  *
- * Will remove a task from the queue. Note that trying to remove the current 
+ * Removes a task from the queue. Note that trying to remove the current 
  * task will fail. If removal succeeded, the @task-removed signal will be 
  * emitted.
  *
  * Once removed, the task will get the state of being cancelled. If the 
- * run_callback argument is TRUE, the callback will still run (for cleaning up)
+ * @run_callback argument is TRUE, the callback will still run (for cleaning
+ * up).
+ *
+ * For more information about this callback, refer to @OAsyncWorkerTaskCallback
+ * and @o_async_worker_task_set_callback.
  *
  * Since: 1.0
  **/
@@ -693,10 +704,9 @@
 /**
  * o_async_worker_get_current:
  * @queue: a #OAsyncWorker
- * @found: A pointer to a boolean which will be assigned to TRUE or FALSE
  * @returns: (caller-owns) (null-ok): the current task or NULL
  *
- * Returns the task thats is currently being processed by 
+ * Returns the task that is currently being processed by 
  * the queue or NULL if none.
  *
  * Since: 1.0
@@ -715,7 +725,6 @@
 		G_UNLOCK(tasks);
 	} else {
 		O_ASYNC_WORKER_OBJECT_NOT_READY(queue);
-		retval = NULL;
 	}
 
 	return retval;
@@ -725,10 +734,10 @@
  * o_async_worker_get_with_id:
  * @queue: a #OAsyncWorker
  * @task_id: the id of the task as returned by @o_async_worker_add
- * @found: A pointer to a boolean which will be assigned to TRUE or FALSE
  * @returns: (caller-owns) (null-ok): the current task or NULL
  *
- * Returns the task that has been identified by task_id or NULL if none.
+ * Returns the task that has been identified by @task_id or NULL 
+ * if none is identified with @task_id.
  *
  * Since: 1.0
  **/
@@ -756,8 +765,6 @@
 		g_list_free (copy);
 		
 		G_UNLOCK(tasks);
-		if (cont) 
-			retval = notfound();
 	} else {
 		O_ASYNC_WORKER_OBJECT_NOT_READY(queue);
 		retval = NULL;
@@ -829,9 +836,9 @@
  * @queue: a #OAsyncWorker
  * @micros: amount of microseconds the queue will have to wait
  * @priority: the priority of the waiter task
- * @returns: the task_id of the waiter task
+ * @returns: the @task_id of the waiter task
  * 
- * Will make the queue wait for at least micros microseconds
+ * Will make the queue wait for at least @micros microseconds
  *
  * Since: 1.0
  **/
@@ -868,7 +875,7 @@
  * o_async_worker_join:
  * @queue: a #OAsyncWorker
  *
- * Blocks until the queue finishes
+ * Blocks @queue until all tasks are finished.
  *
  * Since: 1.0
  **/
@@ -892,11 +899,13 @@
 /**
  * o_async_worker_sched_setaffinity:
  * @queue: a #OAsyncWorker
- * @mask: the mask parameter for the sched_setaffinity function
+ * @mask: the mask parameter for the @sched_setaffinity function
  *
  * Sets the CPU affinity of the thread that will process the tasks.
  * This will only work on platforms that have support for the 
- * sched_setaffinity function (for example Linux).
+ * @sched_setaffinity function (for example Linux).
+ *
+ * For more information: man sched_setaffinity
  *
  * Since: 1.0
  **/
@@ -917,11 +926,13 @@
 /**
  * o_async_worker_sched_getaffinity:
  * @queue: a #OAsyncWorker
- * @returns: the mask parameter for the sched_setaffinity function
+ * @returns: the mask parameter for the @sched_setaffinity function
  *
  * Get the CPU affinity of the thread that will process the tasks
  * This will only work on platforms that have support for the 
- * sched_setaffinity function (for example Linux).
+ * @sched_setaffinity function (for example Linux).
+ *
+ * For more information: man sched_setaffinity
  *
  * Since: 1.0
  */
@@ -942,11 +953,13 @@
 /**
  * o_async_worker_sched_setscheduler:
  * @queue: a #OAsyncWorker
- * @policy: the policy of the sched_setscheduler function
+ * @policy: the policy of the @sched_setscheduler function
  * @param: The const struct sched_param *p of the sched_setscheduler function
  *
  * This will only work on platforms that have support for the 
- * sched_setscheduler function (for example Linux).
+ * @sched_setscheduler function (for example Linux).
+ *
+ * For more information: man sched_setscheduler
  *
  * Since: 1.0
  **/
@@ -973,7 +986,9 @@
  * @returns: the policy
  *
  * This will only work on platforms that have support for the 
- * sched_getscheduler function (for example Linux).
+ * @sched_getscheduler function (for example Linux).
+ *
+ * For more information: man sched_setscheduler
  *
  * Since: 1.0
  **/

Modified: trunk/liboasyncworker/oasyncworkertask.c
==============================================================================
--- trunk/liboasyncworker/oasyncworkertask.c	(original)
+++ trunk/liboasyncworker/oasyncworkertask.c	Sun Apr 27 12:42:11 2008
@@ -1,5 +1,5 @@
 /* OAsyncWorkerTask
- * Copyright (C) 2005, 2006 Philip Van Hoof <pvanhoof gnome org>.
+ * Copyright (C) 2005 - 2008 Philip Van Hoof <pvanhoof gnome org>.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -149,68 +149,68 @@
  
 /**
  * OAsyncWorkerTaskFunc
- * @task: a pointer to the instance of this task
+ * @task: a #OAsyncWorkerTask
  * @arguments: the arguments that have been set with @o_async_worker_task_set_arguments
- * @returns: a gpointer that will also be the second argument of the #OAsyncWorkerTaskCallback
+ * @returns: a pointer that is also the second argument of the #OAsyncWorkerTaskCallback
  *
- * Using @o_async_worker_task_set_func you can assign a function to a task
+ * Using @o_async_worker_task_set_func you can assign a function to a task.
  * This function is the body of the task. It's what needs to be performed in order
  * to complete the task successfully.
  *
  * You can launch new functions from this function. If you don't start a thread
- * in it, they will still belong to the body of the task. If you do start a 
- * thread, the code running in the thread will not be part of the body of this 
- * task. A @g_thread_join will of course work as expected. The body of your tasks
- * will be ran in a thread too. You can join this thread using @o_async_worker_join.
- * Note that all tasks in the worker will need to finish for the join to return.
+ * in it, they still belong to the body of the task. If you do start a thread,
+ * the code running in the thread is not part of the body of this task. A 
+ * @g_thread_join works of course as expected on this thread. The body of your 
+ * tasks runs in a internal thread too. You can join the internal thread using 
+ * @o_async_worker_join. Note that all tasks in the worker need to finish for 
+ * @o_async_worker_join to return.
  *
- * Cancellation points will only trigger a cancel within the body of a task.
- * That body will stop when you return this function, or when a cancellation
+ * Cancellation points only trigger a cancel within the body of a task.
+ * That body stops when you return this function, or when a cancellation
  * point triggered a cancel.
  *
- * If you let it return an allocated pointer, you'll need to free this as a
- * resource in the callback of the task. When a cancellation point triggers a
- * cancellation, that argument will always be NULL (thus unallocated).
+ * If you let it return an allocated pointer, you need to free this as a resource
+ * in the callback of the task. When a cancellation point triggers a cancellation, 
+ * that argument is always NULL (thus unallocated).
  *
  * Since: 1.0
  **/
 
- /**
-  * OAsyncWorkerTaskCallback
-  * @task: a pointer to the instance of this task
-  * @func_result : a pointer to the result of the #OAsyncWorkerTaskFunc
-  *
-  * In this function you need to free all the resources that where allocated
-  * for the task. After the callback will the task itself get freed. So it's
-  * indeed your last chance to free references and allocations.
-  *
-  * If you returned an allocated pointer in the #OAsyncWorkerTaskFunc, you'll
-  * need to free it in this callback too. The returned value of the
-  * #OAsyncWorkerTaskFunc will be the @func_result argument. You can, of course,
-  * use this @func_result argument to pass information from the body of the task,
-  * to the callback. But make sure you free it afterwards.
-  *
-  * Note that if the #OAsyncWorkerTaskFunc returned due to a cancellation, that
-  * @func_result will always be NULL. Deal with it in this callback!
-  *
-  * As this callback happens in the #GMainLoop, you should refrain from doing
-  * lengthy or CPU intensive tasks here. Stick to freeing up resources and 
-  * notifying UI for example. Note that neither AsyncWorker's signals nor these
-  * callbacks happen with the Gdk lock of Gtk+ entered. You must still do the
-  * @gdk_threads_enter and @gdk_threads_leave in the signal handlers and these
-  * callbacks. Read http://live.gnome.org/GdkLock for more information.
-  *
-  * Since: 1.0
-  */
+/**
+ * OAsyncWorkerTaskCallback
+ * @task: a #OAsyncWorkerTask
+ * @func_result : a pointer to the result of the #OAsyncWorkerTaskFunc
+ *
+ * In this function you need to free all the resources that were allocated
+ * for the task.
+ *
+ * If you returned an allocated pointer in the #OAsyncWorkerTaskFunc, you need 
+ * to free it here. The returned value of the #OAsyncWorkerTaskFunc is the
+ * @func_result argument. You can, of course, use @func_result argument to pass
+ * information from the body of the task to the callback.
+ *
+ * Note that if the #OAsyncWorkerTaskFunc returned due to a cancellation, that
+ * @func_result is NULL.
+ *
+ * As this callback happens in the #GMainLoop, you should refrain from doing
+ * CPU intensive tasks in it. Stick to freeing up resources and notifying UI,
+ * for example.
+ *
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information.
+ *
+ * Since: 1.0
+ **/
 
 /**
  * o_async_worker_task_new:
  * @returns: a #OAsyncWorkerTask
  *
- * Will create a new #OAsyncWorkerTask
+ * Creates a new #OAsyncWorkerTask
  *
  * Since: 1.0
- */
+ **/
 OAsyncWorkerTask *
 o_async_worker_task_new (void)
 {
@@ -225,14 +225,13 @@
  * o_async_worker_task_new_with_arguments:
  * @returns: a #OAsyncWorkerTask
  * @arguments: a pointer to the arguments
- * @callback: the callback in which you'll need to free the arguments
+ * @callback: the callback where you need to free the arguments
  *
- * Creates a new #OAsyncWorkerTask and will set its arguments property
+ * Creates a new #OAsyncWorkerTask and sets its arguments property
  *
- * You will need to free the arguments pointer in the callback. This is why you
- * need to give a reference to the @callback too: If you're not planning
- * to use a @callback, you shouldn't set the arguments pointer to an allocated
- * resource.
+ * You need to free the arguments in the callback. This is why you need to give
+ * the @callback too: If you're not planning to use a @callback, you shouldn't set 
+ * the arguments to an allocated resource.
  *
  * Since: 1.0
  **/
@@ -254,17 +253,10 @@
  * @arguments: a pointer to the arguments
  *
  * Set the arguments of the @task. The arguments are passed to the launcher
- * function. You'll need to free it in the callback function which you must
+ * function. You need to free it in the callback function which you must
  * set with @o_async_worker_task_set_callback.
  *
- * It allows you to transfer data to the launcher function. For example function
- * arguments. You can use a GObject or a simple struct. In fact you can use any
- * type of allocated memory. Just remember that you need to free the allocated
- * memory in the callback.
- *
- * If you're not allocating memory (not setting the arguments), you won't need
- * to free it. If you're also returning NULL in the launcher func, you can keep 
- * the callback unassigned.
+ * It allows you to transfer data to the launcher function to the callback. 
  *
  * Since: 1.0
  **/
@@ -288,28 +280,19 @@
  * @task: a #OAsyncWorkerTask
  * @func: a reference to the launcher function
  *
- * Sets the laucher function of @task. It will get as argument a pointer to 
- * arguments property of the @task object. You can unwrap this pointer (for 
- * example a struct) to get the arguments which you might need during the 
- * function itself. You set the arguments property using 
- * @o_async_worker_task_set_arguments.
- *
- * If you're planning to use Gtk+ objects, you'll need to wrap your 
- * gtk-functions with gdk_threads_enter() and gdk_threads_leave() in the body
- * of @task (and in code spawn into a thread). Read http://live.gnome.org/GdkLock 
- * for more information.
- *
- * If you're planning to use non-threadsafe functions and/or objects, make
- * sure that you have proper locking in place.
- *
- * Also read about the callback to know where to free the task-arguments and the
- * result of the launcher function. You set the callback using
- * @o_async_worker_task_set_callback
+ * Sets the laucher function of @task.
+ *
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in @func. Read http://live.gnome.org/GdkLock for 
+ * more information. The execution itself occurs in an internal thread.
+ *
+ * Therefore, if you're planning to use non-threadsafe functions and/or objects,
+ * make sure that you have proper locking in place.
  *
- * There's more information at the OAsyncWorkerTaskFunc section
+ * There's more information at the #OAsyncWorkerTaskFunc section
  *
  * Since: 1.0
- */
+ **/
 void
 o_async_worker_task_set_func (OAsyncWorkerTask *task, OAsyncWorkerTaskFunc func)
 {
@@ -331,24 +314,19 @@
  * @callback: a reference to the callback function
  *
  * Sets the callback function of a task. The callback function is called after
- * the laucher function. It will get as argument a pointer to the result of that
+ * the laucher function. It gets as argument a pointer to the result of that
  * launcher function.
  *
- * If you're planning to use Gtk+ objects, you'll need to wrap your 
- * gtk-functions with gdk_threads_enter() and gdk_threads_leave() in the body of
- * @callback (and in code spawn into a thread). Read http://live.gnome.org/GdkLock
- * for more information.
- *
- * If you're planning to use non-threadsafe functions and/or objects, make
- * sure that you have proper locking in place.
- *
- * The @callback is for example responsible for freeing (or unreferencing) the 
- * arguments property (pointer) of the task and the result of the laucher 
- * function. If you don't free it in the callback, it's likely that you'll 
- * have memory-leaks.
+ * As this callback happens in the #GMainLoop, you should refrain from doing
+ * CPU intensive tasks in it. Stick to freeing up resources and notifying UI,
+ * for example.
+ *
+ * If if you want to use the Gdk or Gtk+ subsystems, you have to acquire the 
+ * Gdk lock yourself in your handlers. Read http://live.gnome.org/GdkLock for 
+ * more information.
  *
  * You can't make a cancellation point trigger a cancel in the @callback.
- * Therefore will the callback always run. It can't be preempted. You can
+ * Therefore the callback always runs. It can't be preempted. You can
  * instruct a cancellation point to launch the callback after cancelling.
  * This way you can free the resources of a finished, removed or cancelled 
  * task in the callback. Check out @o_async_worker_task_cancel_point for
@@ -448,10 +426,7 @@
  * @returns: (caller-owns) (null-ok): a pointer to the #OAsyncWorker or NULL
  *
  * Returns a pointer to the queue that is assigned to process the task. It 
- * will return NULL if no queue has been assigned.
- *
- * Don't use this function in threads. Don't use it in the launcher and/or
- * callback functions of the task.
+ * returns NULL if no queue has been assigned.
  * 
  * Since: 1.0
  **/
@@ -476,8 +451,6 @@
  * @task: a #OAsyncWorkerTask
  * @returns: the priority
  *
- * Will return the priority of a task
- *
  * Since: 1.0
  **/
 gint
@@ -500,11 +473,11 @@
  * @task: a #OAsyncWorkerTask
  * @priority: the priority
  *
- * Will set the priority of a task. A task with a high priority will be
- * processed before a task with a low priority. Note that setting the
- * priority won't preempt the task that's currently being processed. Not even
- * when the current task has a lower priority than the task who's priority is
- * being set.
+ * Sets the priority @task. A task with a high priority will be processed 
+ * before a task with a low priority. Note that setting the priority won't 
+ * preempt the task that's currently being processed. Not even when the 
+ * current task has a lower priority than the task whose priority is being 
+ * set.
  *
  * Since: 1.0
  **/
@@ -565,7 +538,7 @@
 /**
  * o_async_worker_task_is_cancelled:
  * @task: a #OAsyncWorkerTask
- * @returns: wether the task was cancelled
+ * @returns: whether or not the task was cancelled
  * 
  * This can be useful in a callback to know whether or not you need to free
  * the result of the launcher function. For example in case you've been using
@@ -573,8 +546,7 @@
  *
  * Note that to be cancelled, the task really needed to get cancelled. The
  * @o_async_worker_task_cancel method only requests a cancellation. The task then
- * still needs to get at a cancellation point. Only then will this property will
- * be set.
+ * still needs to get at a cancellation point. Only then this property is set.
  *
  * Since: 1.0
  **/
@@ -597,17 +569,15 @@
 /**
  * o_async_worker_task_cancel_point:
  * @task: a #OAsyncWorkerTask
- * @run_callback: wether to run the callback after cancellation
+ * @run_callback: whether to run the callback after cancellation
  * 
  * Define a location where the processing of the task may cancel. You can choose
  * on a per-point basis whether the callback of the task must still be called.
- * If you choose not to, you wont get the chance to free the arguments pointer
+ * If you choose not to, you won't get the chance to free the arguments pointer
  * or other resources being used by the task!
  *
- * You won't need to free the result of the launcher function since it wont get
- * the chance to return the value (else it wasn't cancelled). You can use 
- * @o_async_worker_task_is_cancelled to know, in that callback, whether the task
- * was cancelled.
+ * The return value of the launcher function is set automatically to NULL in case
+ * of an actual cancellation.
  *
  * Since: 1.0
  **/
@@ -641,11 +611,11 @@
  * o_async_worker_task_request_cancel:
  * @task: a #OAsyncWorkerTask
  * 
- * Set a task to be cancelled. The cancellation itself will only trigger when
+ * Set a task to be cancelled. The cancellation itself only triggers when
  * during the processing of the task-body, a cancellation point is found.
  * Also see the information about @o_async_worker_task_cancel_point.
  *
- * Note that you need to setup a #GMainLoop for this to work correctly. All
+ * Note that you need to run a #GMainLoop for this to work correctly. All
  * Gtk+ applications (after doing gtk_main) have this.
  *
  * Since: 1.0
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]