Update internal docs

Author: gilzoide

include/dispatch_queue.hpp

@@ -13,8 +13,8 @@ namespace dispatch_queue {
 class dispatch_queue {
 public:
 	/**
-	 * Create a synchronous dispatch queue.
-	 * In synchronous mode, tasks are executed immediately when calling `dispatch`.
+	 * Create an immediate dispatch queue.
+	 * In immediate mode, tasks are executed immediately when calling `dispatch`.
 	 */
 	dispatch_queue();
 
@@ -28,12 +28,12 @@ class dispatch_queue {
 	 * Initializes dispatch queue with `thread_count` background threads and a worker initialization functor.
 	 *
 	 * @param thread_count  Number of background threads used to run tasks.
-	 *                      If 0, the dispatch queue is created in synchronous mode.
+	 *                      If 0, the dispatch queue is created in immediate mode.
 	 *                      If 1, tasks will run serially in background, one at a time, without any concurrency.
 	 *                      Otherwise, `thread_count` threads will be created and tasks may run concurrently.
 	 *                      Pass a negative number to use the default value of `std::thread::hardware_concurrency()` threads.
 	 * @param worker_init  Functor called inside worker threads for initialization, receiving as argument the worker index.
-	 *                     May be used to set the thread name, for example.
+	 *                     May be used to set the thread name or initialize thread local variables, for example.
 	 */
 	template<typename Fn>
 	dispatch_queue(int thread_count, Fn&& worker_init) {
@@ -55,7 +55,7 @@ class dispatch_queue {
 
 	/**
 	 * Dispatch a task that calls `f` with forwarded arguments `args`.
-	 * If the dispatch queue is in synchronous mode, the task is processed immediately in the calling thread.
+	 * If the dispatch queue is in immediate mode, the task is processed immediately in the calling thread.
 	 * @param f Functor to be executed
 	 * @param args Arguments forwarded to `f`
 	 * @returns Future for getting `f` result.
@@ -71,6 +71,7 @@ class dispatch_queue {
 	 * @param f Functor to be executed
 	 * @param args Arguments forwarded to `f`
 	 * @returns Future for getting `f` result.
+	 * @see main_loop
 	 */
 	template<typename F, typename... Args, typename Ret = detail::function_result<F, Args...>>
 	task<Ret> dispatch_main(F&& f, Args&&... args) {
@@ -84,7 +85,7 @@ class dispatch_queue {
 
 	/**
 	 * Number of threads used for processing tasks.
-	 * This will be 0 on synchronous mode.
+	 * This will be 0 in immediate mode.
 	 */
 	int thread_count() const;
 
@@ -106,7 +107,7 @@ class dispatch_queue {
 
 	/**
 	 * Invoke main loop tasks dispatched using `dispatch_main`.
-	 * This should be called in you application main loop.
+	 * This should be called in your application's main loop.
 	 */
 	void main_loop();
 
@@ -118,7 +119,7 @@ class dispatch_queue {
 	/**
 	 * Wait until all pending tasks finish processing.
 	 * Blocks until specified `timeout_duration` has elapsed or all queued tasks complete, whichever comes first.
-	 * @returns `false` if the timeout has expired, otherwise `true`.
+	 * @returns `true` if all tasks finished processing, otherwise `false`.
 	 */
 	template<class Rep, class Period>
 	bool wait_for(const std::chrono::duration<Rep, Period>& timeout_duration) {
@@ -133,7 +134,7 @@ class dispatch_queue {
 	/**
 	 * Wait until all pending tasks finish processing.
 	 * Blocks until the specified `timeout_time` has been reached or all queued tasks complete, whichever comes first.
-	 * @returns `false` if the timeout has expired, otherwise `true`.
+	 * @returns `true` if all tasks finished processing, otherwise `false`.
 	 */
 	template<class Clock, class Duration>
 	bool wait_until(const std::chrono::time_point<Clock, Duration>& timeout_time) {
@@ -146,8 +147,8 @@ class dispatch_queue {
 	}
 
 	/**
-	 * Cancel pending tasks, wait and release the used Threads.
-	 * The queue now runs in synchronous mode.
+	 * Cancel pending tasks, wait and release the used threads.
+	 * The queue now runs in immediate mode.
 	 * It is safe to call this more than once.
 	 */
 	void shutdown();

include/task.hpp

@@ -33,7 +33,7 @@ class task {
 	 * Add a continuation `f` that is guaranteed to run after this task finishes.
 	 *
 	 * If the task is not finished yet, `f` will run right after the task finishes in the same thread where the task ran.
-	 * Otherwise, `f` will run immediately in the current thread.
+	 * Otherwise, `f` will run immediately in the calling thread.
 	 */
 	template<typename F>
 	requires (detail::is_instance_of<T, task>::value)
@@ -53,7 +53,7 @@ class task {
 	 * Add a continuation `f` that is guaranteed to run after this task finishes.
 	 *
 	 * If the task is not finished yet, `f` will run right after the task finishes in the same thread where the task ran.
-	 * Otherwise, `f` will run immediately in the current thread.
+	 * Otherwise, `f` will run immediately in the calling thread.
 	 */
 	template<typename F>
 	auto then(F&& f) const {
@@ -102,7 +102,7 @@ class task {
 	 * If the task is pending (`get_state() == task_state::pending`), blocks until task finishes or until the specified `timeout_duration` has elapsed.
 	 * Otherwise returns immediately without blocking.
 	 *
-	 * @returns `false` if the timeout has expired, otherwise `true`.
+	 * @returns `true` if the task is finished, otherwise `false`.
 	 */
 	template<class Rep, class Period>
 	bool wait_for(const std::chrono::duration<Rep, Period>& timeout_duration) const {
@@ -115,7 +115,7 @@ class task {
 	 * If the task is pending (`get_state() == task_state::pending`), blocks until task finishes or until the specified `timeout_time` has been reached.
 	 * Otherwise returns immediately without blocking.
 	 *
-	 * @returns `false` if the timeout has expired, otherwise `true`.
+	 * @returns `true` if the task is finished, otherwise `false`.
 	 */
 	template<class Clock, class Duration>
 	bool wait_until(const std::chrono::time_point<Clock, Duration>& timeout_time) const {
@@ -162,6 +162,7 @@ class task {
 private:
 	std::shared_ptr<detail::task_future<T>> future;
 
+	/// Helper function for creating a task of another type from within this class
 	template<typename U>
 	static task<U> to_task(std::shared_ptr<detail::task_future<U>> future) {
 		return task<U>(future);

include/task_future.hpp

@@ -14,7 +14,7 @@ namespace dispatch_queue {
 enum class task_state {
 	/// Task is either queued for execution or still running
 	pending,
-	/// Task is ready and the result value is readily available
+	/// Task finished successfully and the result value is readily available
 	ready,
 	/// Task failed with an exception
 	failed,

src/dispatch_queue.cpp

@@ -3,7 +3,6 @@
 namespace dispatch_queue {
 
 dispatch_queue::dispatch_queue()
-	: dispatch_queue(0)
 {
 }