[libgee] Fix valadoc syntax and extend Traversable.tee documentation

[Maciej Marcin Piechotka <mpiechotka src gnome org>]

commit ba9894127c4f18955f7d080da71a5a7500c92889
Author: Maciej Piechotka <uzytkownik2 gmail com>
Date:   Sat Sep 13 13:45:17 2014 +0200

    Fix valadoc syntax and extend Traversable.tee documentation

 gee/future.vala      |   62 +++++++++++++++++++++++++-------------------------
 gee/promise.vala     |    4 +-
 gee/task.vala        |   16 ++++++------
 gee/traversable.vala |    8 +++++-
 4 files changed, 47 insertions(+), 43 deletions(-)
---
diff --git a/gee/future.vala b/gee/future.vala
index 338237b..c9b8c9a 100644
--- a/gee/future.vala
+++ b/gee/future.vala
@@ -28,16 +28,16 @@ using GLib;
  *
  * All methods can be called from many threads as part of interface.
  *
+ * Note: Statement that call does not block does not mean that it is lock-free.
+ *   Internally the implementation is allowed to take mutex but it should guarantee
+ *   that it is not for a long time (including blocking on anything else, I/O calls
+ *   or callbacks).
+ *
  * @see Promise
  * @see Lazy
  * @see task
  * @see async_task
  * @since 0.11.0
- *
- * Note: Statement that call does not block does not mean that it is lock-free.
- *   Internally the implementation is allowed to take mutex but it should guarantee
- *   that it is not for a long time (including blocking on anything else, I/O calls
- *   or callbacks).
  */
 [GenericAccessors]
 public interface Gee.Future<G> : Object {
@@ -80,7 +80,7 @@ public interface Gee.Future<G> : Object {
        /**
         * Waits until the value is ready.
         *
-        * @returns The { link value} associated with future
+        * @return The { link value} associated with future
         * @see ready
         * @see wait_until
         * @see wait_async
@@ -93,7 +93,7 @@ public interface Gee.Future<G> : Object {
         *
         * @param end_time The time when the wait should finish
         * @param value The { link value} associated with future if the wait was successful
-        * @returns ``true`` if the value was ready within deadline or ``false`` otherwise
+        * @return ``true`` if the value was ready within deadline or ``false`` otherwise
         * @see ready
         * @see wait
         * @see wait_async
@@ -104,7 +104,7 @@ public interface Gee.Future<G> : Object {
        /**
         * Reschedules the callback until the { link value} is available.
         *
-        * @returns The { link value} associated with future
+        * @return The { link value} associated with future
         * @see ready
         * @see wait
         * @see wait_until
@@ -117,16 +117,16 @@ public interface Gee.Future<G> : Object {
         * Maps a future value to another value by a function and returns the
         * another value in future.
         *
-        * @param func Function applied to { link value}
-        * @returns Value returned by function
-        *
-        * @see flat_map
-        * @see light_map
-        *
         * Note: As time taken by function might not contribute to
         *   { link wait_until} and the implementation is allowed to compute
         *   value eagerly by { link when_done} it is recommended to use
         *   { link task} and { link flat_map} for longer computation.
+        *
+        * @param func Function applied to { link value}
+        * @return Value returned by function
+        *
+        * @see flat_map
+        * @see light_map
         */
        [CCode (ordering = 3)]
        public virtual Future<A> map<A> (owned MapFunc<A, G> func) {
@@ -147,13 +147,6 @@ public interface Gee.Future<G> : Object {
         * Maps a future value to another value by a function and returns the
         * another value in future.
         *
-        * @param func Function applied to { link value}
-        * @returns Value returned by function
-        *
-        * @see flat_map
-        * @see map
-        * @since 0.11.4
-        *
         * Note: The function may be reevaluated at any time and it might
         *   be called lazily. Therefore it is recommended for it to be
         *   idempotent. If the function needs to be called eagerly or have
@@ -163,6 +156,13 @@ public interface Gee.Future<G> : Object {
         *   { link wait_until} and the implementation is allowed to compute
         *   value eagerly by { link when_done} it is recommended to use
         *   { link task} and { link flat_map} for longer computation.
+        *
+        * @param func Function applied to { link value}
+        * @return Value returned by function
+        *
+        * @see flat_map
+        * @see map
+        * @since 0.11.4
         */
        [CCode (ordering = 10, cname = "gee_future_light_map_fixed", vfunc_name = "light_map_fixed")]
        public virtual Future<A> light_map<A> (owned LightMapFunc<A, G> func) {
@@ -181,15 +181,15 @@ public interface Gee.Future<G> : Object {
         * Combines values of two futures using a function returning the combined
         * value in future (call does not block).
         *
-        * @param join_func Function applied to values
-        * @param second Second parameter
-        * @returns A combine value
-        * @since 0.11.4
-        *
         * Note: As time taken by function does not contribute to
         *   { link wait_until} and the implementation is allowed to compute
         *   value eagerly by { link when_done} it is recommended to return a
         *   future from { link task} and use { link flat_map} for longer computation.
+        *
+        * @param join_func Function applied to values
+        * @param second Second parameter
+        * @return A combine value
+        * @since 0.11.4
         */
        [CCode (ordering = 5)]
        public virtual Future<B> zip<A, B> (owned ZipFunc<G, A, B> zip_func, Future<A> second) {
@@ -213,16 +213,16 @@ public interface Gee.Future<G> : Object {
        /**
         * Maps a future value to another future value which is returned (call does not block).
         *
-        * @param func Function applied to { link value}
-        * @returns Value of a future returned by function
-        *
-        * @see map
-        *
         * Note: As time taken by function does not contribute to
         *   { link wait_until} and the implementation is allowed to compute
         *   value eagerly by { link when_done} it is recommended to put the
         *   larger computation inside the returned future for example by
         *   { link task}
+        *
+        * @param func Function applied to { link value}
+        * @return Value of a future returned by function
+        *
+        * @see map
         */
        [CCode (ordering = 6)]
        public virtual Gee.Future<A> flat_map<A>(owned FlatMapFunc<A, G> func) {
diff --git a/gee/promise.vala b/gee/promise.vala
index 74d4de0..90eac07 100644
--- a/gee/promise.vala
+++ b/gee/promise.vala
@@ -50,7 +50,7 @@ public class Gee.Promise<G> {
        /**
         * Sets the value of the future.
         *
-        * @params value Value of future
+        * @param value Value of future
         */
        public void set_value (owned G value) {
                _future.set_value ((owned)value);
@@ -59,7 +59,7 @@ public class Gee.Promise<G> {
        /**
         * Sets the exception.
         *
-        * @params exception Exception thrown
+        * @param exception Exception thrown
         */
        public void set_exception (owned GLib.Error exception) {
                _future.set_exception ((owned)exception);
diff --git a/gee/task.vala b/gee/task.vala
index 9e398bf..80d6dbd 100644
--- a/gee/task.vala
+++ b/gee/task.vala
@@ -27,15 +27,15 @@ namespace Gee {
         * Schedules a task to execute asynchroniously. Internally one
         * of threads from pool will execute the task.
         *
-        * @params task Task to be executed
-        * @returns Future value returned by task
-        * @see async_task
-        * @since 0.11.0
-        *
         * Note: There is limited number of threads unless environment variable
         *   ``GEE_NUM_THREADS`` is set to -1. It is not adviced to call I/O or
         *   block inside the taks. If necessary it is possible to create a new one
         *   by anyther call.
+        *
+        * @param task Task to be executed
+        * @return Future value returned by task
+        * @see async_task
+        * @since 0.11.0
         */
        public Future<G> task<G>(owned Task<G> task) throws GLib.ThreadError {
                TaskData<G> tdata = new TaskData<G>();
@@ -50,13 +50,13 @@ namespace Gee {
         * Continues the execution asynchroniously in helper thread. Internally
         * one of threads from pool will execute the task.
         *
-        * @see task
-        * @since 0.11.0
-        *
         * Note: There is limited number of threads unless environment variable
         *   ``GEE_NUM_THREADS`` is set to -1. It is not adviced to call I/O or
         *   block inside the taks. If necessary it is possible to create a new one
         *   by anyther call.
+        *
+        * @see task
+        * @since 0.11.0
         */
        public async void async_task() throws GLib.ThreadError {
                task<bool>(async_task.callback);
diff --git a/gee/traversable.vala b/gee/traversable.vala
index 58aba5a..77ce6ea 100644
--- a/gee/traversable.vala
+++ b/gee/traversable.vala
@@ -399,11 +399,15 @@ public interface Gee.Traversable<G> : Object {
         * Note: The returned arrey might contain parent iterator if it is allowed
         *   by implementation. For example the iteration over collection does
         *   not need to generate and cache the results.
+        *   In such case it is recommended to return the value as the first element
+        *   of the array. This allows the consumer to check just the first element
+        *   if it can perform optimizations for such case. However it //must// not
+        *   depend on the order (that's for optimization only).
         *
-        * Note: the resulting iterators does not need to be thread safe.
+        * Note: The resulting iterators does not need to be thread safe.
         *
         * @param forks Number of iterators in array
-        * @returns An array with created iterators
+        * @return An array with created iterators
         * @since 0.11.5
         */
        [CCode (ordering = 9)]