Explicitly make the hashes, equality and comparation immutable

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);
 }