[libgee] Explicitly make the hashes, equality and comparation immutable

[Maciej Marcin Piechotka <mpiechotka src gnome org>]

commit b12c25fac688138779477c7ff010d7cbb72c6516
Author: Maciej Piechotka <uzytkownik2 gmail com>
Date:   Sat Sep 13 14:25:29 2014 +0200

    Explicitly make the hashes, equality and comparation immutable

 gee/comparable.vala |   12 ++++++++++++
 gee/hashable.vala   |   21 ++++++++++++++++++---
 gee/hashset.vala    |   33 +++++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 3 deletions(-)
---
diff --git a/gee/comparable.vala b/gee/comparable.vala
index 9639483..6ee158e 100644
--- a/gee/comparable.vala
+++ b/gee/comparable.vala
@@ -24,6 +24,18 @@
  * This interface defines a total ordering among instances of each class
  * implementing it.
  *
+ * In other words:
+ *
+ *   * It's irreflexive: For all `a` it holds that `a.compare_to(a) == 0`
+ *   * It's transitive: For all `a`, `b` and `c` if `a.compare_to(b) < 0` and
+ *     `b.compare_to(c) < 0` then `a.compare_to(c) < 0`.
+ *   * It's trichotomous: For all `a` and `b` it holds that
+ *     `a.compare_to(b) = -b.compare_to(a)`.
+ *
+ * Note: The relationship must be immutable. In other words if at one point of
+ *   program `a.compare_to(b)` had certain value then call `a.compare_to(b)`
+ *   //must always// return the original value until end of `a` and `b` lifetime.
+ *
  * @see Hashable
  */
 public interface Gee.Comparable<G> : Object {
diff --git a/gee/hashable.vala b/gee/hashable.vala
index 8a2c785..dd5f3c0 100644
--- a/gee/hashable.vala
+++ b/gee/hashable.vala
@@ -23,21 +23,36 @@
 /**
  * This interface defines a hash function amongs instances of each class
  * implementing it.
- * 
+ *
  * @see Comparable
  */
 public interface Gee.Hashable<G> : Object {
        /**
         * Computes hash for an objects. Two hashes of equal objects have to be
-        * equal. Hash have to not change during lifetime of object.
+        * equal.
+        *
+        * Note: Hash //must not// change during lifetime of an object.
         *
         * @return hash of an object
         */
        public abstract uint hash ();
 
        /**
-        * Compares this object with the specifed object.
+        * Compares this object with the specifed object. This defines the
+        * equivalence relation between them.
+        *
+        * In other words:
+        *
+        *  * It must be reflexive: for all objects `a` it holds that
+        *    `a.equal_to(a)`.
+        *  * It must be symmetric: for all objects `a` and `b` if
+        *    `a.equal_to(b)` then `b.equal_to(a)`.
+        *  * It must be transitive: if `a.equal_to(b)` and `b.equal_to(c)` then
+        *    `a.equal_to(c)`.
+        *
+        * Note: Relationship //must not// change during lifetime of an object.
         *
+        * @param object Object this objest is compared with
         * @return true if objects are equal
         */
        public abstract bool equal_to (G object);
diff --git a/gee/hashset.vala b/gee/hashset.vala
index 2736554..959d592 100644
--- a/gee/hashset.vala
+++ b/gee/hashset.vala
@@ -26,7 +26,40 @@
 using GLib;
 
 namespace Gee {
+       /**
+        * A function producing a hash for an object. Two hashes of equal
+        * objects (as specified by corresponding { link EqualDataFunc}) have to
+        * be equal.
+        *
+        * Note: Hash for a given object //must not// change during the lifetime
+        *   of delegate.
+        *
+        * @param v Hashed value
+        * @return Hash for given value
+        *
+        * @see Hashable
+        */
        public delegate uint HashDataFunc<T> (T v);
+       /**
+        * A function comparing two object defining equivalence relationship.
+        *
+        * In other words if `equal_to` is `EqualDataFunc` then:
+        *
+        *  * It must be reflexive: for all objects `a` it holds that
+        *    `equal_to(a, a)`.
+        *  * It must be symmetric: for all objects `a` and `b` if
+        *    `equal_to(a, b)` then `equal_to(b, a)`.
+        *  * It must be transitive: if `equal_to(a, b)` and `equal_to(b, c)`
+        *    then `equal_to(a, c)`
+        *
+        * Note: The relationship //must not// change during lifetime of the
+        *   delegate.
+        *
+        * @param v Hashed value
+        * @return Hash for given value
+        *
+        * @see Hashable
+        */
        public delegate bool EqualDataFunc<T> (T a, T b);
 }