[libgee] Adding a first very basic documentation to data types implementations.

[Didier 'Ptitjes' Villevalois <dvillevalois src gnome org>]

commit e1899db8fb4d7b5b17fe35007f288f8aa3718000
Author: Julien Peeters <contact julienpeeters fr>
Date:   Fri Sep 4 18:07:08 2009 +0200

    Adding a first very basic documentation to data types implementations.
    
    When a data type method is already documented in a super class or
    in an interface the '@inheritDoc' parameter is set.

 gee/abstractcollection.vala |   47 ++++++++++++++++++++++----
 gee/abstractlist.vala       |   27 +++++++++++++++
 gee/abstractmap.vala        |   36 ++++++++++++++++++++
 gee/arraylist.vala          |   47 +++++++++++++++++++++++++++
 gee/functions.vala          |   32 ++++++++++++++++++
 gee/hashset.vala            |   27 +++++++++++++++
 gee/linkedlist.vala         |   47 +++++++++++++++++++++++++--
 gee/readonlycollection.vala |   48 +++++++++++++++++++++++++++
 gee/readonlylist.vala       |   75 +++++++++++++++++++++++++++++++++++++++++++
 gee/readonlyset.vala        |   48 +++++++++++++++++++++++++++
 gee/treemap.vala            |   34 +++++++++++++++++++
 gee/treeset.vala            |   25 ++++++++++++++
 12 files changed, 482 insertions(+), 11 deletions(-)
---
diff --git a/gee/abstractcollection.vala b/gee/abstractcollection.vala
index a93c0e5..9a1f412 100644
--- a/gee/abstractcollection.vala
+++ b/gee/abstractcollection.vala
@@ -26,24 +26,41 @@
  */
 public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collection<G> {
 
-	//
-	// Inherited from Collection<G>
-	//
-
+	/**
+	 * @inheritDoc
+	 */
 	public abstract int size { get; }
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool is_empty {
 		get { return size == 0; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract bool contains (G item);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract bool add (G item);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract bool remove (G item);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract void clear ();
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual G[] to_array() {
 		G[] array = new G[size];
 		int index = 0;
@@ -53,6 +70,9 @@ public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collectio
 		return array;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool add_all (Collection<G> collection) {
 		if (collection.is_empty) {
 			return false;
@@ -65,6 +85,9 @@ public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collectio
 		return changed;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool contains_all (Collection<G> collection) {
 		if (collection.size > size) {
 			return false;
@@ -78,6 +101,9 @@ public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collectio
 		return true;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool remove_all (Collection<G> collection) {
 		bool changed = false;
 		foreach (G item in collection) {
@@ -86,6 +112,9 @@ public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collectio
 		return changed;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool retain_all (Collection<G> collection) {
 		bool changed = false;
 		G[] items = to_array ();
@@ -98,13 +127,15 @@ public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collectio
 		return changed;
 	}
 
-	//
-	// Inherited from Iterable<G>
-	//
-
+	/**
+	 * @inheritDoc
+	 */
 	public Type element_type {
 		get { return typeof (G); }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract Iterator<G> iterator ();
 }
diff --git a/gee/abstractlist.vala b/gee/abstractlist.vala
index 5a4b919..6f4af8b 100644
--- a/gee/abstractlist.vala
+++ b/gee/abstractlist.vala
@@ -26,26 +26,53 @@
  */
 public abstract class Gee.AbstractList<G> : Gee.AbstractCollection<G>, List<G> {
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract new G? get (int index);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract new void set (int index, G item);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract int index_of (G item);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract void insert (int index, G item);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract void remove_at (int index);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract List<G>? slice (int start, int stop);
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual G? first () {
 		return get (0);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual G? last () {
 		return get (size - 1);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual void insert_all (int index, Collection<G> collection) {
 		foreach (G item in collection) {
 			insert(index, item);
diff --git a/gee/abstractmap.vala b/gee/abstractmap.vala
index 5676a34..a0192f5 100644
--- a/gee/abstractmap.vala
+++ b/gee/abstractmap.vala
@@ -26,32 +26,65 @@
  */
 public abstract class Gee.AbstractMap<K,V> : Object, Map<K,V> {
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract int size { get; }
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool is_empty {
 		get { return size == 0; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract Set<K> get_keys ();
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract Collection<V> get_values ();
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract bool contains (K key);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract new V? get (K key);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract new void set (K key, V value);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract bool remove (K key, out V? value = null);
 
+	/**
+	 * @inheritDoc
+	 */
 	public abstract void clear ();
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual void set_all (Map<K,V> map) {
 		foreach (K key in map.get_keys ()) {
 			set (key, map.get (key));
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool remove_all (Map<K,V> map) {
 		bool changed = false;
 		foreach (K key in map.get_keys ()) {
@@ -60,6 +93,9 @@ public abstract class Gee.AbstractMap<K,V> : Object, Map<K,V> {
 		return changed;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public virtual bool contains_all (Map<K,V> map) {
 		foreach (K key in map.get_keys ()) {
 			if (!contains (key)) {
diff --git a/gee/arraylist.vala b/gee/arraylist.vala
index 0496c48..8eae29b 100644
--- a/gee/arraylist.vala
+++ b/gee/arraylist.vala
@@ -40,6 +40,11 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 	// concurrent modification protection
 	private int _stamp = 0;
 
+	/**
+	 * Array list implementation constructor.
+	 *
+	 * @param equal_func an optional elements equality testing function.
+	 */
 	public ArrayList (EqualFunc? equal_func = null) {
 		if (equal_func == null) {
 			equal_func = Functions.get_equal_func_for (typeof (G));
@@ -47,14 +52,23 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		this.equal_func = equal_func;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override Gee.Iterator<G> iterator () {
 		return new Iterator<G> (this);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool contains (G item) {
 		return (index_of (item) != -1);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override int index_of (G item) {
 		for (int index = 0; index < _size; index++) {
 			if (equal_func (_items[index], item)) {
@@ -64,6 +78,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return -1;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override G? get (int index) {
 		assert (index >= 0);
 		assert (index < _size);
@@ -71,6 +88,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return _items[index];
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void set (int index, G item) {
 		assert (index >= 0);
 		assert (index < _size);
@@ -78,6 +98,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		_items[index] = item;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool add (G item) {
 		if (_size == _items.length) {
 			grow_if_needed (1);
@@ -87,6 +110,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return true;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void insert (int index, G item) {
 		assert (index >= 0);
 		assert (index <= _size);
@@ -99,6 +125,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		_stamp++;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove (G item) {
 		for (int index = 0; index < _size; index++) {
 			if (equal_func (_items[index], item)) {
@@ -109,6 +138,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return false;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void remove_at (int index) {
 		assert (index >= 0);
 		assert (index < _size);
@@ -120,6 +152,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		_stamp++;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void clear () {
 		for (int index = 0; index < _size; index++) {
 			_items[index] = null;
@@ -128,6 +163,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		_stamp++;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override List<G>? slice (int start, int stop) {
 		return_val_if_fail (start <= stop, null);
 		return_val_if_fail (start >= 0, null);
@@ -141,6 +179,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return slice;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool add_all (Collection<G> collection) {
 		if (collection.is_empty) {
 			return false;
@@ -154,6 +195,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return true;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove_all (Collection<G> collection) {
 		bool changed = false;
 		for (int index = 0; index < _size; index++) {
@@ -166,6 +210,9 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 		return changed;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool retain_all (Collection<G> collection) {
 		bool changed = false;
 		for (int index = 0; index < _size; index++) {
diff --git a/gee/functions.vala b/gee/functions.vala
index 8b0c99e..9303e0d 100644
--- a/gee/functions.vala
+++ b/gee/functions.vala
@@ -26,6 +26,13 @@ namespace Gee {
 
 	public class Functions {
 
+		/**
+		 * Get a equality testing function for a given type.
+		 *
+		 * @param t the type which to get an equality testing function for.
+		 *
+		 * @return the equality testing function corresponding to the given type.
+		 */
 		public static EqualFunc get_equal_func_for (Type t) {
 			if (t == typeof (string)) {
 				return str_equal;
@@ -34,6 +41,13 @@ namespace Gee {
 			}
 		}
 
+		/**
+		 * Get a hash function for a given type.
+		 *
+		 * @param t the type which to get the hash function for.
+		 *
+		 * @return the hash function corresponding to the given type.
+		 */
 		public static HashFunc get_hash_func_for (Type t) {
 			if (t == typeof (string)) {
 				return str_hash;
@@ -42,6 +56,13 @@ namespace Gee {
 			}
 		}
 
+		/**
+		 * Get a comparator function for a given type.
+		 *
+		 * @param t the type which to get a comparator function for.
+		 *
+		 * @return the comparator function corresponding to the given type.
+		 */
 		public static CompareFunc get_compare_func_for (Type t) {
 			if (t == typeof (string)) {
 				return (CompareFunc) strcmp;
@@ -51,6 +72,17 @@ namespace Gee {
 		}
 	}
 
+	/**
+	 * Compares to arbitrary elements together.
+	 *
+	 * The comparison is done on pointers and not on values behind.
+	 *
+	 * @param _val1 the first value to compare.
+	 * @param _val2 the second value to compare.
+	 *
+	 * @return a negative value if _val1 is lesser than _val2, a positive value
+	 *         if _val1 is greater then _val2 and zero if both are equal.
+	 */
 	public static int direct_compare (void* _val1, void* _val2) {
 		long val1 = (long)_val1, val2 = (long)_val2;
 		if (val1 > val2) {
diff --git a/gee/hashset.vala b/gee/hashset.vala
index d30d222..17e07c4 100644
--- a/gee/hashset.vala
+++ b/gee/hashset.vala
@@ -32,8 +32,14 @@ public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
 		get { return _nnodes; }
 	}
 
+	/**
+	 * Hash function.
+	 */
 	public HashFunc hash_func { private set; get; }
 
+	/**
+	 * Equality testing function.
+	 */
 	public EqualFunc equal_func { private set; get; }
 
 	private int _array_size;
@@ -46,6 +52,12 @@ public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
 	private const int MIN_SIZE = 11;
 	private const int MAX_SIZE = 13845163;
 
+	/**
+	 * Hash set implementation constructor.
+	 *
+	 * @param hash_func an optional hash function.
+	 * @param equal_func an optional equality testing function.
+	 */
 	public HashSet (HashFunc? hash_func = null, EqualFunc? equal_func = null) {
 		if (hash_func == null) {
 			hash_func = Functions.get_hash_func_for (typeof (G));
@@ -71,15 +83,24 @@ public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
 		return node;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool contains (G key) {
 		Node<G>** node = lookup_node (key);
 		return (*node != null);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override Gee.Iterator<G> iterator () {
 		return new Iterator<G> (this);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool add (G key) {
 		Node<G>** node = lookup_node (key);
 		if (*node != null) {
@@ -94,6 +115,9 @@ public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove (G key) {
 		Node<G>** node = lookup_node (key);
 		if (*node != null) {
@@ -112,6 +136,9 @@ public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
 		return false;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void clear () {
 		for (int i = 0; i < _array_size; i++) {
 			Node<G> node = (owned) _nodes[i];
diff --git a/gee/linkedlist.vala b/gee/linkedlist.vala
index 98c35db..c3adc20 100644
--- a/gee/linkedlist.vala
+++ b/gee/linkedlist.vala
@@ -33,8 +33,16 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 	private Node? _head = null;
 	private Node? _tail = null;
 
+	/**
+	 * Equality testing between elements function.
+	 */
 	public EqualFunc equal_func { private set; get; }
 
+	/**
+	 * Linked list implementation constructor.
+	 *
+	 * @param equal_func an optional equality testing function.
+	 */
 	public LinkedList (EqualFunc? equal_func = null) {
 		if (equal_func == null) {
 			equal_func = Functions.get_equal_func_for (typeof (G));
@@ -42,20 +50,30 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		this.equal_func = equal_func;
 	}
 
-	// Iterable<G>
+	/**
+	 * @inheritDoc
+	 */
 	public override Gee.Iterator<G> iterator () {
 		return new Iterator<G> (this);
 	}
 
-	// Collection<G>
+	/**
+	 * @inheritDoc
+	 */
 	public override int size {
 		get { return this._size; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool contains (G item) {
 		return this.index_of (item) != -1;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool add (G item) {
 		Node<G> n = new Node<G> (item);
 		if (this._head == null && this._tail == null) {
@@ -73,6 +91,9 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		return true;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove (G item) { // Should remove only the first occurence (a test should be added)
 		for (Node<G> n = this._head; n != null; n = n.next) {
 			if (this.equal_func (item, n.data)) {
@@ -83,13 +104,18 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		return false;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void clear () {
 		++this._stamp;
 		this._head = this._tail = null;
 		this._size = 0;
 	}
 
-	// List<G>
+	/**
+	 * @inheritDoc
+	 */
 	public override G? get (int index) {
 		assert (index >= 0);
 		assert (index < this._size);
@@ -102,6 +128,9 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void set (int index, G item) {
 		assert (index >= 0);
 		assert (index < this._size);
@@ -111,6 +140,9 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		n.data = item;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override int index_of (G item) {
 		int result = -1;
 		int idx = 0;
@@ -125,6 +157,9 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		return result;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void insert (int index, G item) {
 		assert (index >= 0);
 		assert (index <= this._size);
@@ -155,6 +190,9 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void remove_at (int index) {
 		assert (index >= 0);
 		assert (index < this._size);
@@ -164,6 +202,9 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 		this._remove_node (n);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override List<G>? slice (int start, int stop) {
 		return_val_if_fail (start <= stop, null);
 		return_val_if_fail (start >= 0, null);
diff --git a/gee/readonlycollection.vala b/gee/readonlycollection.vala
index 870eb1c..c3496e5 100644
--- a/gee/readonlycollection.vala
+++ b/gee/readonlycollection.vala
@@ -26,28 +26,49 @@ using GLib;
  * Represents a read-only collection of items.
  */
 public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
+
+	/**
+	 * @inheritDoc
+	 */
 	public int size {
 		get { return _collection.size; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool is_empty {
 		get { return _collection.is_empty; }
 	}
 
+	/**
+	 * Generic collection property.
+	 */
 	public Collection<G> collection {
 		construct { _collection = value; }
 	}
 
 	private Collection<G> _collection;
 
+	/**
+	 * Read only collection constructor.
+	 *
+	 * @param collection the collection to decorate (may be null).
+	 */
 	public ReadOnlyCollection (Collection<G>? collection = null) {
 		this.collection = collection;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Type element_type {
 		get { return typeof (G); }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Gee.Iterator<G> iterator () {
 		if (_collection == null) {
 			return new Iterator<G> ();
@@ -56,6 +77,9 @@ public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 		return _collection.iterator ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains (G item) {
 		if (_collection == null) {
 			return false;
@@ -64,22 +88,37 @@ public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 		return _collection.contains (item);
 	}
 
+	/**
+	 * Unimplemented method (read only collection).
+	 */
 	public bool add (G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only collection).
+	 */
 	public bool remove (G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only collection).
+	 */
 	public void clear () {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only collection).
+	 */
 	public bool add_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains_all (Collection<G> collection) {
 		foreach (G element in collection) {
 			if (!contains (element)) {
@@ -89,14 +128,23 @@ public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 		return true;
 	}
 
+	/**
+	 * Unimplemented method (read only collection).
+	 */
 	public bool remove_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only collection).
+	 */
 	public bool retain_all(Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public G[] to_array() {
 		return _collection.to_array ();
 	}
diff --git a/gee/readonlylist.vala b/gee/readonlylist.vala
index 0fc1b55..fdedc26 100644
--- a/gee/readonlylist.vala
+++ b/gee/readonlylist.vala
@@ -26,28 +26,49 @@ using GLib;
  * Represents a read-only collection of items in a well-defined order.
  */
 public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
+
+	/**
+	 * @inheritDoc
+	 */
 	public int size {
 		get { return _list.size; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool is_empty {
 		get { return _list.is_empty; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public List<G> list {
 		construct { _list = value; }
 	}
 
 	private List<G> _list;
 
+	/**
+	 * Read only list implementation constrcutor.
+	 *
+	 * @param list the list to decorate (may be null).
+	 */
 	public ReadOnlyList (List<G>? list = null) {
 		this.list = list;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Type element_type {
 		get { return typeof (G); }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Gee.Iterator<G> iterator () {
 		if (_list == null) {
 			return new Iterator<G> ();
@@ -56,6 +77,9 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.iterator ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains (G item) {
 		if (_list == null) {
 			return false;
@@ -64,6 +88,9 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.contains (item);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public int index_of (G item) {
 		if (_list == null) {
 			return -1;
@@ -72,22 +99,37 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.index_of (item);
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public bool add (G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public bool remove (G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public void insert (int index, G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public void remove_at (int index) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public new G? get (int index) {
 		if (_list == null) {
 			return null;
@@ -96,22 +138,37 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.get (index);
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public new void set (int index, G o) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public void clear () {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public List<G>? slice (int start, int stop) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public bool add_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains_all (Collection<G> collection) {
 		if (_list == null) {
 			return false;
@@ -119,14 +176,23 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.contains_all (collection);
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public bool remove_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public bool retain_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public G? first () {
 		if (_list == null) {
 			return null;
@@ -135,6 +201,9 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.first ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public G? last () {
 		if (_list == null) {
 			return null;
@@ -143,10 +212,16 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 		return _list.last ();
 	}
 
+	/**
+	 * Unimplemented method (read only list).
+	 */
 	public void insert_all (int index, Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public G[] to_array() {
 		return _list.to_array ();
 	}
diff --git a/gee/readonlyset.vala b/gee/readonlyset.vala
index b7bdb7a..828d0d0 100644
--- a/gee/readonlyset.vala
+++ b/gee/readonlyset.vala
@@ -26,28 +26,49 @@ using GLib;
  * Represents a read-only collection of items without duplicates.
  */
 public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
+
+	/**
+	 * @inheritDoc
+	 */
 	public int size {
 		get { return _set.size; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool is_empty {
 		get { return _set.is_empty; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public new Set<G> set {
 		construct { _set = value; }
 	}
 
 	private Set<G> _set;
 
+	/**
+	 * Read only set implementation constructor.
+	 *
+	 * @param set the set to decorate.
+	 */
 	public ReadOnlySet (Set<G>? set = null) {
 		this.set = set;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Type element_type {
 		get { return typeof (G); }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Gee.Iterator<G> iterator () {
 		if (_set == null) {
 			return new Iterator<G> ();
@@ -56,6 +77,9 @@ public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
 		return _set.iterator ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains (G item) {
 		if (_set == null) {
 			return false;
@@ -64,22 +88,37 @@ public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
 		return _set.contains (item);
 	}
 
+	/**
+	 * Unimplemented method (read only set).
+	 */
 	public bool add (G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only set).
+	 */
 	public bool remove (G item) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only set).
+	 */
 	public void clear () {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only set).
+	 */
 	public bool add_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains_all (Collection<G> collection) {
 		foreach (G element in collection) {
 			if (!contains (element)) {
@@ -89,14 +128,23 @@ public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
 		return true;
 	}
 
+	/**
+	 * Unimplemented method (read only set).
+	 */
 	public bool remove_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only set).
+	 */
 	public bool retain_all (Collection<G> collection) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public G[] to_array() {
 		return _set.to_array ();
 	}
diff --git a/gee/treemap.vala b/gee/treemap.vala
index db943cf..25111aa 100644
--- a/gee/treemap.vala
+++ b/gee/treemap.vala
@@ -30,11 +30,24 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		get { return _size; }
 	}
 
+	/**
+	 * The keys comparator function.
+	 */
 	public CompareFunc key_compare_func { private set; get; }
+
+	/**
+	 * The values equality testing function.
+	 */
 	public EqualFunc value_equal_func { private set; get; }
 
 	private int _size = 0;
 
+	/**
+	 * Tree map implementation constructor.
+	 *
+	 * @param key_compare_func an optional key comparator function.
+	 * @param value_equal_func an optional values equality testing function.
+	 */
 	public TreeMap (CompareFunc? key_compare_func = null, EqualFunc? value_equal_func = null) {
 		if (key_compare_func == null) {
 			key_compare_func = Functions.get_compare_func_for (typeof (K));
@@ -46,10 +59,16 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		this.value_equal_func = value_equal_func;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override Set<K> get_keys () {
 		return new KeySet<K,V> (this);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override Collection<V> get_values () {
 		return new ValueCollection<K,V> (this);
 	}
@@ -80,6 +99,9 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		return n == null || n.color == Node.Color.BLACK;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool contains (K key) {
 		weak Node<K, V>? cur = root;
 		while (cur != null) {
@@ -95,6 +117,9 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		return false;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override V? get (K key) {
 		weak Node<K, V>? cur = root;
 		while (cur != null) {
@@ -135,6 +160,9 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		fix_up (ref node);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void set (K key, V value) {
 		set_to_node (ref root, key, value, null, null);
 		root.color = Node.Color.BLACK;
@@ -227,6 +255,9 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove (K key, out V? value = null) {
 		V node_value;
 		bool b = remove_from_node (ref root, key, out node_value);
@@ -242,6 +273,9 @@ public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 		return b;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void clear () {
 		root = null;
 		_size = 0;
diff --git a/gee/treeset.vala b/gee/treeset.vala
index 8b6d1fd..61537ff 100644
--- a/gee/treeset.vala
+++ b/gee/treeset.vala
@@ -30,10 +30,18 @@ public class Gee.TreeSet<G> : AbstractCollection<G>, Set<G> {
 		get {return _size;}
 	}
 
+	/**
+	 * The elements comparator function.
+	 */
 	public CompareFunc compare_func { private set; get; }
 
 	private int _size = 0;
 
+	/**
+	 * Tree set implementation constructor.
+	 *
+	 * @param compare_func an optional elements comparator function.
+	 */
 	public TreeSet (CompareFunc? compare_func = null) {
 		if (compare_func == null) {
 			compare_func = Functions.get_compare_func_for (typeof (G));
@@ -41,6 +49,9 @@ public class Gee.TreeSet<G> : AbstractCollection<G>, Set<G> {
 		this.compare_func = compare_func;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool contains (G item) {
 		weak Node<G>? cur = root;
 		while (cur != null) {
@@ -120,6 +131,11 @@ public class Gee.TreeSet<G> : AbstractCollection<G>, Set<G> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 *
+	 * If the element already exists in the set it will not be added twice.
+	 */
 	public override bool add (G item) {
 		bool r = add_to_node (ref root, item, null, null);
 		root.color = Node.Color.BLACK;
@@ -202,6 +218,9 @@ public class Gee.TreeSet<G> : AbstractCollection<G>, Set<G> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove (G item) {
 		bool b = remove_from_node (ref root, item);
 		if (root != null) {
@@ -211,12 +230,18 @@ public class Gee.TreeSet<G> : AbstractCollection<G>, Set<G> {
 		return b;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void clear () {
 		root = null;
 		_size = 0;
 		stamp++;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override Gee.Iterator<G> iterator () {
 		return  new Iterator<G> (this);
 	}