Merge improved docs from stable into trunk (2/2)

git-svn-id: http://opensource.mlba-team.de/svn/xdispatch/trunk@379 9e4c620c-c391-4b63-a7fb-4924991ea895
digiverse · Apr 13, 2012 · 7c64089 · 7c64089
1 parent 8101975
commit 7c64089
Show file tree

Hide file tree

Showing 16 changed files with 129 additions and 19 deletions.
diff --git a/QtDispatch.dox b/QtDispatch.dox
@@ -1,27 +1,19 @@
 /**
-\addtogroup QtDispatch
+@defgroup qtdispatch libQtDispatch
 
-@author Marius Zwicker / MLBA
-@date 28.03.2011
+QtDispatch is an additional Qt Module building on QtCore and providing a custom Qt adapted interface to use \ref dispatch.
 
-@section qt_about Overview
+This interface is fully compatible with the generic C++ interface provided by
+\ref xdispatch.
 
-QtDispatch is an additional Qt Module building on QtCore and providing a custom Qt adapted interface
-to use libDispatch. This interface is fully compatible with the generic C++ interface provided by
-\ref XDispatch.
-
-As integration into Qt, it is possible to dispatch QRunnables onto groups and queues as well.
-For integrating the main queue into your Qt Application we created a (currently experimental) QDispatchCoreApplication
-and QDispatchApplication using the dispatch mechanisms for handling all incoming events and thus
-using the dispatch main loop. To simplify the use of blocks within your Qt code as well, we added
+As integration into Qt, it is possible to dispatch QRunnables onto groups and queues the same way as when executing them on a QThreadPool. Going along with that we added
 QBlockRunnable, a simple QRunnable created by passing an individual block.
 
-@section qt_use Usage
+For integrating the main queue into your Qt Application there is a QDispatchApplication which can be used as a drop-in replacement to QApplication. It will call xdispatch::exec() internally and ensure that all work dispatched to the main queue is executed on the main/gui thread. That way it is very easy to send gui updates to the main thread. All other functionality is equal to that of QApplication.
 
-You can use QtDispach (in case you have Qt > 4.6 available on your system) by including QtDispatch or
-one of the individual modules (all found within include/QtDispatch, link with the QtDispatch lib). 
-This will automatically include  all other needed headers as well. Below you find a list of the available classes:
+@section qt_use Usage
 
+You can use QtDispach (in case you have Qt > 4.6 available on your system) by including the QtDispatch header or one of the individual modules - this will automatically include  all other needed headers as well. Below you find a list of the available classes.
  - QDispatch
  - QDispatchQueue
  - QDispatchGroup
@@ -33,5 +25,11 @@ This will automatically include  all other needed headers as well. Below you fin
  - QDispatchApplication
  - QDispatchSource
  - QDispatchSourceType
-
+
+The corresponding headers have the same name and can be included all by once using
+@code
+#include <QtDispatch/QtDispatch>
+@endcode
+
+Please link your program with qtdispatch and xdispatch.
 */
diff --git a/dispatch.dox b/dispatch.dox
@@ -0,0 +1,24 @@
+/**
+@defgroup dispatch libdispatch
+
+The library libdispatch is an abstract model for expressing concurrency via simple but powerful API.
+
+At the core, libdispatch provides serial FIFO queues to which blocks may be
+submitted. Blocks submitted to these dispatch queues are invoked on a pool
+of threads fully managed by the system. No guarantee is made regarding
+which thread a block will be invoked on; however, it is guaranteed that only
+one block submitted to the FIFO dispatch queue will be invoked at a time.
+
+When multiple queues have blocks to be processed, the system is free to
+allocate additional threads to invoke the blocks concurrently. When the
+queues become empty, these threads are automatically released.
+
+@section d_use Usage
+
+All header files needed for using libdispatch can be included by typing
+@code
+#include <dispatch/dispatch.h>
+@endcode
+You will need to link against the dispatch library.
+
+*/
diff --git a/include/QtDispatch/qblockrunnable.h b/include/QtDispatch/qblockrunnable.h
@@ -26,6 +26,11 @@
 #include <QRunnable>
 #include "qdispatchglobal.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 #ifdef XDISPATCH_HAS_BLOCKS
 
 QT_BEGIN_HEADER
@@ -72,4 +77,6 @@ QT_END_HEADER
 
 #endif
 
+/** @} */
+
 #endif /* QBLOCKRUNNABLE_H_ */
diff --git a/include/QtDispatch/qdispatch.h b/include/QtDispatch/qdispatch.h
@@ -26,6 +26,11 @@
 #include "qdispatchglobal.h"
 #include "qdispatchqueue.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -125,4 +130,6 @@ class Q_DISPATCH_EXPORT QDispatch {
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_H_ */
diff --git a/include/QtDispatch/qdispatchapplication.h b/include/QtDispatch/qdispatchapplication.h
@@ -26,6 +26,11 @@
 #include <QApplication>
 #include "qdispatchglobal.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -50,4 +55,6 @@ class Q_DISPATCH_EXPORT QDispatchApplication : public QApplication {
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_APPLICATION_H_ */
diff --git a/include/QtDispatch/qdispatchcoreapplication.h b/include/QtDispatch/qdispatchcoreapplication.h
@@ -28,6 +28,11 @@
 
 #include <qcoreapplication.h>
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -64,4 +69,6 @@ class Q_DISPATCH_EXPORT QDispatchCoreApplication : public QCoreApplication {
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_EVENTDISPATCHER_H_ */
diff --git a/include/QtDispatch/qdispatchglobal.h b/include/QtDispatch/qdispatchglobal.h
@@ -26,6 +26,11 @@
 
 #include <QtCore/qglobal.h>
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 #ifndef QT_MODULE
 # define QT_MODULE(X)
 # define QT_LICENSED_MODULE(X)
@@ -62,4 +67,6 @@ typedef xdispatch::synclock QDispatchSynclock;
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_GLOBAL_H_ */
diff --git a/include/QtDispatch/qdispatchgroup.h b/include/QtDispatch/qdispatchgroup.h
@@ -28,6 +28,10 @@
 #include "qdispatchglobal.h"
 #include "qblockrunnable.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
 
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
@@ -149,4 +153,6 @@ Q_DECL_EXPORT QDebug operator<<(QDebug, const QDispatchGroup&);
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_GROUP_H_ */
diff --git a/include/QtDispatch/qdispatchqueue.h b/include/QtDispatch/qdispatchqueue.h
@@ -28,6 +28,11 @@
 #include "qdispatchglobal.h"
 #include "qblockrunnable.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -143,4 +148,6 @@ Q_DECL_EXPORT QDebug operator<<(QDebug dbg, const QDispatchQueue& q);
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_QUEUE */
diff --git a/include/QtDispatch/qdispatchsemaphore.h b/include/QtDispatch/qdispatchsemaphore.h
@@ -24,6 +24,11 @@
 
 #include "qdispatchglobal.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -79,4 +84,6 @@ Q_DECL_EXPORT QDebug operator<<(QDebug, const QDispatchSemaphore&);
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_SEMAPHORE_H_ */
diff --git a/include/QtDispatch/qdispatchsource.h b/include/QtDispatch/qdispatchsource.h
@@ -28,6 +28,11 @@
 #include "qdispatchglobal.h"
 #include "qblockrunnable.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -304,4 +309,6 @@ class Q_DISPATCH_EXPORT QDispatchSource : public QObject {
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_SOURCE_H_ */
diff --git a/include/QtDispatch/qdispatchtimer.h b/include/QtDispatch/qdispatchtimer.h
@@ -27,6 +27,11 @@
 
 #include <qobject.h>
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -140,4 +145,6 @@ class Q_DISPATCH_EXPORT QDispatchTimer : public QObject, private xdispatch::time
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QDISPATCH_SEMAPHORE_H_ */
diff --git a/include/QtDispatch/qiterationblockrunnable.h b/include/QtDispatch/qiterationblockrunnable.h
@@ -27,6 +27,11 @@
 
 #include "qdispatchglobal.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 #ifdef XDISPATCH_HAS_BLOCKS
 
 QT_BEGIN_HEADER
@@ -71,4 +76,6 @@ QT_END_HEADER
 
 #endif
 
+/** @} */
+
 #endif /* QITERATIONBLOCKRUNNABLE_H_ */
diff --git a/include/QtDispatch/qiterationrunnable.h b/include/QtDispatch/qiterationrunnable.h
@@ -26,6 +26,11 @@
 #include <QRunnable>
 #include "qdispatchglobal.h"
 
+/**
+ * @addtogroup qtdispatch
+ * @{
+ */
+
 QT_BEGIN_HEADER
 QT_BEGIN_NAMESPACE
 
@@ -61,4 +66,6 @@ class Q_DISPATCH_EXPORT QIterationRunnable : public QRunnable {
 QT_END_NAMESPACE
 QT_END_HEADER
 
+/** @} */
+
 #endif /* QITERATIONRUNNABLE_H_ */
diff --git a/include/dispatch/queue.h b/include/dispatch/queue.h
@@ -415,8 +415,9 @@ dispatch_set_target_queue(dispatch_object_t object, dispatch_queue_t queue);
  * This function "parks" the main thread and waits for blocks to be submitted
  * to the main queue. This function never returns.
  *
- * Applications that call NSApplicationMain() or CFRunLoopRun() on the
- * main thread do not need to call dispatch_main().
+ * @remarks Applications that call NSApplicationMain() or CFRunLoopRun() on the
+ * main thread, call xdispatch::exec() or exec() on a QDispatchApplication object
+ * do not need to call dispatch_main().
  */
 
 DISPATCH_EXPORT  

diff --git a/include/xdispatch/base.h b/include/xdispatch/base.h
@@ -318,6 +318,10 @@ XDISPATCH_EXPORT time as_delayed_time(uint64_t delay, time base = time_now);
     Call this somewhere within the main thread to enable
     dispatching operations to the main queue. Will never
     return.
+
+    @remarks Applications that call dispatch_main(), NSApplicationMain(), NSApplicationMain()
+    or call exec() on a QDispatchApplication object do not need to call this.
+    @see dispatch_main()
     */
 XDISPATCH_EXPORT void exec();