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

git-svn-id: http://opensource.mlba-team.de/svn/xdispatch/trunk@378 9e4c620c-c391-4b63-a7fb-4924991ea895

CHANGELOG.dox

@@ -1,5 +1,5 @@
 /**
-@page change_log CHANGELOG
+@page change_log Changelog
 
 @section changes-61 Version 0.6.1
 

README.dox

@@ -1,53 +1,54 @@
 /**
-@mainpage libXDispatch - Overview
+@mainpage XDispatch - Overview
 @section intro_sec Introduction
 
-libXDispatch provides the power of libdispatch (or Grand Central Dispatch if you like) not only on Mac OS 10.6+ 
-but on Windows and Linux. On each platform libDispatch is built on, the build 
-system (in our case CMake) will automatically search for existing dispatch implementations  (possibly integrated
-deeper than this user space implementation can do). If found, this "native"
-implementation will automatically be used. If no implementation is available, our own will be used. 
+XDispatch provides the power of Grand Central Dispatch not only on Mac OS 10.6+
+but also on Windows and Linux. The XDispatch framework consists of three libraries:
+ - \ref dispatch
+ - \ref xdispatch
+ - \ref qtdispatch
 
-Currently a native libdispatch is available on Mac OS X 10.6+ only and therefore will only be used when built on that 
-platform.
 
 Please see Apple's documentation on http://developer.apple.com and the libdispatch project at http://libdispatch.macosforge.org
 as well.
 
 See the \ref change_log or the <a href="http://opensource.mlba-team.de/xdispatch/news.htm">NEWS PAGE</a> to get to know the recent development.
 
-@subsection x1 Original (plain C) Interface
+@subsection x1 libdispatch - the 'original' (plain C) Interface
 
-The entire libdispatch interface is available and can be found in the following files:
-
- - <a href="queue_8h.html">dispatch/queue.h</a>
- - <a href="group_8h.html">dispatch/group.h</a>
- - <a href="time_8h.html">dispatch/time.h</a>
- - <a href="object_8h.html">dispatch/object.h</a>
- - <a href="semaphore_8h.html">dispatch/semaphore.h</a>
- - <a href="source_8h.html">dispatch/source.h</a>
+The entire Grand Central Dispatch interface is available and can be found in \ref dispatch library.
 
 Please note that including <dispatch/dispatch.h> is entirely sufficient and will
 automatically include all other headers as well.
+
+@subsubsection @section x111 Use of system provided implementations
+
+On some platforms (namely Mac OS) a version of the libdispatch library is installed by default.
+Consequently on each platform xdispatch is built on, the build system will automatically search for existing dispatch implementations  (possibly integrated
+deeper than this user space implementation can do). If found, this "native"
+implementation will automatically be used. If no implementation is available, our own will be used.
+
+Currently a native libdispatch is available on Mac OS X 10.6+ only and therefore will only be used when built on that
+platform.
 
-@subsection x11 C++ Interface
+@subsection x11 libxdispatch - a C++ Interface
 
 As a first level of abstraction we created a plain C++ interface providing a more object-oriented way of programming. Detailed
-information can be found at the related page \ref XDispatch.
+information can be found at the related page \ref xdispatch.
 
 @subsection x2 Qt Interface
 
-Additionally an interface wrapping libdispatch as Qt Classes was created. All needed work was done to integrate it with Qt's main
-event loop. For more information, please see the document on \ref QtDispatch
+Additionally an interface design in a 'Qt-like' fashion was created. All needed work was done to integrate it with Qt's main
+event loop. For more information, please see the document on \ref qtdispatch
 
-@subsection x3 GCD's use of Blocks
+@section x3 GCD's use of Blocks
 
 When Apple introduced Grand Central Dispatch it extended its compilers by a new feature they called "Blocks". Basically this
 is lambdas (sometimes called closures as well). They allow an easier way to utilize the libdispatch api and are available when using
 Clang or the gcc 4.2 that's shipped with Apple's current Developer Tools.
 
 On compilers implementing the block syntax, it is fully functional when using this port. However we support way
-more compilers when using the C++ interface \ref XDispatch. Please see the documentation found over there for
+more compilers when using the C++ interface \ref xdispatch. Please see the documentation found over there for
 extended details.
 
 @section x4 Requirements
@@ -60,14 +61,14 @@ Since version 0.3 libXDispatch is provided as ready-to-use binary package within
 section at <a href="http://opensource.mlba-team.de/xdispatch/files">http://opensource.mlba-team.de/xdispatch/files</a>.
 
 The current xdispatch sources can both be browsed at http://opensource.mlba-team.de/websvn 
-and is accessable using subversion as well. To get your own copy, run:
+and are accessable using subversion as well. To get your own copy, run:
 
 @code
 svn co http://opensource.mlba-team.de/svn/xdispatch/trunk
 @endcode
 
 Please be aware that this is a project still in progress. As such we might introduce interface
-changes and new functionality until reaching version 1.0 - have a look at the CHANGELOG
+changes and new functionality until reaching version 1.0 - have a look at the \ref changelog
 for details and the current progress. When using this library within a project we recommend to use
 one of the tagged versions or the stable branch available by using subversion:
 
@@ -76,9 +77,12 @@ svn co http://opensource.mlba-team.de/svn/xdispatch/tags/<version number here>
 svn co http://opensource.mlba-team.de/svn/xdispatch/branches/stable
 @endcode
 
-Those versions were tested on all supported platforms and should be stable to use.
+Those versions were tested on a lot of platforms and should be stable to use. Nevertheless you are encouraged to update
+to the latest version whenever a new release is published as this way you will benefit of further bugfixes, enhanced performance and
+new functionality of libxdispatch providing even better means for implementing concurrent software.
 
-Please do not forget to take a look at the requirements section and \ref tutorial. In case you want to report a
-bug or contribute to this project, please contact us using email via xdispatch (at) mlba-team.de
+Please do not forget to take a look at the sections concerning \ref requirements and a way for \ref tutorial. In case you want to report a
+bug or contribute to this project, please contact us using email via xdispatch (at) mlba-team.de or subscribe to the mailing list at <a href="http://opensource.mlba-team.de/mailman/listinfo/libxdispatch">
+http://opensource.mlba-team.de/mailman/listinfo/libxdispatch</a>
 
-**/
+**/

REQUIREMENTS.dox

@@ -1,68 +1,68 @@
 /**
-@page requirements REQUIREMENTS
-@author Marius Zwicker / MLBA
+@page requirements Requirements
 
 @section supp Supported Environments
 
-libXDispatch was tested on and currently run's on the following operating systems:
+XDispatch was tested on and currently run's on the following operating systems:
 
- - Mac OS 10.6
- - Windows XP SP3 and Windows 7 32bit/64bit
+ - Mac OS 10.6 'Snow Leopard', 10.7 'Lion'
+ - Windows XP SP3 32bit and Windows 7 32bit/64bit
  - Debian 6.0
- - openSUSE 11.4
- - Ubuntu 10.10
+ - openSUSE 11.4 64bit
+ - Ubuntu 10.10 and 11.10, both 32bit and 64bit
 
 We expect it to run on various other flavors of Linux as well, however we had no chance
 to test it yet. The officially supported development environments and/or toolchains include:
 
- - Clang 2.0
- - XCode 4 (using the clang backend)
- - GCC 4.2+ – to use lambdas we recommend GCC 4.5.1+
+ - Clang 2.0, 3.0 and 3.1
+ - XCode 4 (using the Clang backend)
+ - GCC 4.2+ – to use lambdas we recommend GCC 4.6.x
  - Visual Studio 2008 SP1 - tested for 32bit, might also work with 64bit
  - Visual Studio 2010, building both 32bit and 64bit binaries
  - MinGW (shipping gcc 4.5.x)
-
-libXDispatch is coming as ready-to-use, i.e. we include all dependencies (except Qt) within our
-source tree. Of course you do not need to use our versions of the third party libraries, but use
-your own. To do so, you should have the following libraries installed and have them reachable by
-compiler and linker:
-<ul>
- <li>
-	libkqueue (at least version 0.5, for full platform support we are shipping with the trunk revision 523)
-	The sources and further information can be found at http://mark.heily.com/project/libkqueue
- </li>
- <li>
-	libpthread_workqueue (trunk revision 119 recommended and tested)
-	More information about this library is available at http://mark.heily.com/libpthreadworkqueue
- </li>
-</ul>
-Please note that both libraries are available as debian packages using apt or aptitude as well. Our
-build scripts will automatically detect any pre-installed versions.
-
-Of course we welcome any news on sucessful builds on other operating systems / toolchains currently not declared as
-officially supported. Please contact us to report any success stories.
 
 @section dev Developing with libXDispatch
 
 When intending to develop with libXDispatch please ensure you are using one of the supported
 environments. Afterwards go to the <a href="http://opensource.mlba-team.de/xdispatch/files">downloads page</a> and select the appropriate binary package. Included
-are the necessary headers and library files you have to link with. Normally linking with xdispatch should
-be sufficient. When using the Qt interface, you have to link with QtDispatch as well. Please note that you 
+are the necessary headers and library files you have to link with. Normally linking with xdispatch or dispatch should
+be sufficient, see the appropriate documentation for details. When using the Qt interface, you have to link with qtdispatch as well. Please note that you
 have to link with the Qt additionally in case you want to use the QtDispatch library.
 
 Another possible approach is to include the sources directly into your own source tree, e.g. by using svn:externals and referring to our stable branch. This is the
 recommended way when already using CMake. When doing so, all you need to do is to add the xdispatch directory by using the add_subdirectory() call, setting the proper
 global includes to our include/ directory and linking your own targets with the targets xdispatch and/or QtDispatch.
 
 For examples and demonstrations of xdispatch and the Grand Central Dispatch approach, we recommend to have a look at \ref tutorial and refer to Apple's Online Documentation
-mentioned in the README.dox file.
+mentioned in the @ref into_sec.
 
 @section build Building libXDispatch
 
 Building libXDispatch means you either intend to build your own copy or want to directly integrate the
-libXDispatch sources with your project (easily done when using CMake) 
+libXDispatch sources with your project (easily done when using CMake).
+
+libXDispatch is coming as ready-to-use, i.e. we include all dependencies (except Qt) within our
+source tree. Of course you do not need to use our versions of the third party libraries, but use
+your own. To do so, you should have the following libraries and their development files installed and have them reachable by
+compiler and linker:
+<ul>
+ <li>
+        libkqueue (at least version 0.5, for full platform support we are shipping with the trunk revision 523)
+        The sources and further information can be found at http://mark.heily.com/project/libkqueue
+ </li>
+ <li>
+        libpthread_workqueue (trunk revision 119 recommended and tested)
+        More information about this library is available at http://mark.heily.com/libpthreadworkqueue
+ </li>
+ <li>
+        libblocks-runtime (when using Clang as a target compiler)
+        More information about this library is available at http://mackyle.github.com/blocksruntime/
+</ul>
+Please note that all those libraries are available as debian packages using apt or aptitude as well. Our
+build scripts will automatically detect any pre-installed versions.
 
-Additionally to a supported toolchain / operating system you need CMake 2.8+ installed and reachable in your 
+
+Additionally to a supported toolchain / operating system you need CMake 2.8+ installed and reachable in your
 path. If you want to build QtDispatch, please ensure that you have a SDK for Qt 4.7.0+ installed and
 qmake is reachable in your path as well.
 If all this is satisfied, get your copy of the current sources (see \ref m1), enter the root directory (where
@@ -72,8 +72,8 @@ you find the README.dox) and run (depending on you platform):
 @code
 cmake
 @endcode
-Afterwards you should find a solution file in your xdispatch folder. Build it and the binaries can be 
-found within the 'Bin' directory.
+Afterwards you should find a solution file in your xdispatch folder. Build it and the binaries can be
+found within the 'bin' directory.
 
 @subsection x42 On Linux (Makefiles)
 @code
@@ -86,10 +86,21 @@ When finished, all binaries can be found within the 'Bin' directory.
 @code
 cmake -G "XCode"
 @endcode
-You should find an xcodeproject in your xdispatch folder. Upon build completion, all binaries 
-can be found in the 'Bin' directory as well.
+You should find an xcodeproject in your xdispatch folder. Upon build completion, all binaries
+can be found in the 'bin' directory as well.
+
+@subsection x44 CMake
+Alternatively you can simply include the sources from with a CMakeLists.txt configuration to be built along with your complete project:
+@code
+add_subdirectory(xdispatch)
+@endcode
 
-Other generators are available as well, please consult the CMake documentation at 
+Other generators are available as well, please consult the CMake documentation at
 http://www.cmake.org for more detailed information.
+
+@section story Success Stories
+
+Of course we welcome any news on sucessful builds on other operating systems / toolchains currently not declared as
+officially supported. Please contact us to report any success stories.
 
-*/
+*/

docs/Doxyfile

@@ -25,7 +25,7 @@ DOXYFILE_ENCODING      = UTF-8
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = libXDispatch
+PROJECT_NAME           = XDispatch
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 
@@ -578,6 +578,7 @@ INPUT                  = include \
 					     README.dox \
 						 Tutorial.dox \
 						 xdispatch.dox \
+                                                 dispatch.dox \
 						 QtDispatch.dox \
 						 REQUIREMENTS.dox
 

docs/footer.htm

@@ -1,6 +1,6 @@
 <hr size="1"><address style="text-align: right; margin: 15px;"><small>
 Generated on $datetime for $projectname by&nbsp;<a href="http://www.doxygen.org/index.html">Doxygen $doxygenversion</a><br/>
-&copy 2011-2012 MLBA (<a href="http://www.mlba-team.de/impressum.htm">about</a> | <a href="http://www.mlba-team.de/impressum.htm">privacy</a>) All Rights reserved.</small></address>
+&copy 2010-2012 MLBA (<a href="http://www.mlba-team.de/impressum.htm">about</a> | <a href="http://www.mlba-team.de/impressum.htm">privacy</a>) All Rights reserved.</small></address>
 
 <!-- Piwik -->
 <script type="text/javascript">

docs/header.htm

@@ -10,7 +10,7 @@
 	  $(document).ready(function() { searchBox.OnSelectItem(0); });
 	</script>
 </head><body>
-<div class="custom_header" style="padding-left: 150px;">libXDispatch 0.7.0</div>
+<div class="custom_header" style="padding-left: 150px;">XDispatch 0.7.0</div>
 
 <div id="global_nav">
 	<a href="http://opensource.mlba-team.de/xdispatch/news.htm">

include/dispatch/base.h

@@ -21,6 +21,11 @@
 #ifndef __DISPATCH_BASE__
 #define __DISPATCH_BASE__
 
+/**
+ * @addtogroup dispatch
+ * @{
+ */
+
 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
 #endif
@@ -86,14 +91,8 @@ typedef void (*dispatch_function_t)(void *);
 # endif
 #endif
 
-#ifndef DISPATCH_PTR
-# ifdef _WIN32
-#  define DISPATCH_PTR *
-# else
-#  define DISPATCH_PTR
-# endif
-#endif
 
+/** @} */
 
 #endif
 

include/dispatch/benchmark.h

@@ -27,6 +27,8 @@
 #ifndef __DISPATCH_BENCHMARK__
 #define __DISPATCH_BENCHMARK__
 
+#ifndef XDISPATCH_DOYGEN_RUN
+
 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
 #include <dispatch/base.h> // for HeaderDoc
@@ -76,4 +78,6 @@ dispatch_benchmark_f(size_t count, void *ctxt, void (*func)(void *));
 
 __DISPATCH_END_DECLS
 
+#endif /* XDISPATCH_DOXYGEN_RUN */
+
 #endif

include/dispatch/dispatch.h

@@ -21,6 +21,11 @@
 #ifndef __DISPATCH_PUBLIC__
 #define __DISPATCH_PUBLIC__
 
+/**
+ * @addtogroup dispatch
+ * @{
+ */
+
 #ifdef __APPLE__
 #include <Availability.h>
 #include <TargetConditionals.h>
@@ -63,5 +68,6 @@
 
 #undef __DISPATCH_INDIRECT__
 
+/** @} */
 
 #endif

include/dispatch/group.h

@@ -21,6 +21,11 @@
 #ifndef __DISPATCH_GROUP__
 #define __DISPATCH_GROUP__
 
+/**
+ * @addtogroup dispatch
+ * @{
+ */
+
 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
 #include "base.h" // for HeaderDoc
@@ -236,4 +241,6 @@ dispatch_group_leave(dispatch_group_t group);
 
 __DISPATCH_END_DECLS
 
+/** @} */
+
 #endif

include/dispatch/object.h

@@ -21,6 +21,11 @@
 #ifndef __DISPATCH_OBJECT__
 #define __DISPATCH_OBJECT__
 
+/**
+ * @addtogroup dispatch
+ * @{
+ */
+
 #ifndef __DISPATCH_INDIRECT__
 #error "Please #include <dispatch/dispatch.h> instead of this file directly."
 #include "base.h" // for HeaderDoc
@@ -165,4 +170,6 @@ dispatch_resume(dispatch_object_t object);
 
 __DISPATCH_END_DECLS
 
+/** @} */
+
 #endif