GNOME.org
 

[libgee] Adding a short descriptive introduction for each implementation class.

commit 9ba500a1ea54d4fa73e831dc98d96802d3c94ef3
Author: Julien Peeters <contact julienpeeters fr>
Date:   Sat Sep 5 11:21:29 2009 +0200

    Adding a short descriptive introduction for each implementation class.
    
    Generally this introduction consists of a implementation description and
    few word about comparison with other structures.

 gee/abstractcollection.vala |    6 ++++-
 gee/abstractlist.vala       |    7 +++++-
 gee/abstractmap.vala        |   12 +++++++--
 gee/arraylist.vala          |   18 +++++++++++++-
 gee/collection.vala         |    3 +-
 gee/functions.vala          |    8 +++++-
 gee/hashmap.vala            |   48 ++++++++++++++++++++++++++++++++++++++-
 gee/hashset.vala            |   17 ++++++++++---
 gee/iterable.vala           |    3 +-
 gee/iterator.vala           |    3 +-
 gee/linkedlist.vala         |   11 ++++++--
 gee/list.vala               |    2 +-
 gee/map.vala                |    2 +-
 gee/readonlycollection.vala |   13 ++++++++--
 gee/readonlylist.vala       |   13 ++++++++--
 gee/readonlymap.vala        |   53 ++++++++++++++++++++++++++++++++++++++++++-
 gee/readonlyset.vala        |   12 +++++++--
 gee/set.vala                |    2 +-
 gee/treemap.vala            |   18 +++++++++++---
 gee/treeset.vala            |   17 +++++++++++--
 20 files changed, 226 insertions(+), 42 deletions(-)
---
diff --git a/gee/abstractcollection.vala b/gee/abstractcollection.vala
index 9a1f412..9ca2988 100644
--- a/gee/abstractcollection.vala
+++ b/gee/abstractcollection.vala
@@ -22,7 +22,11 @@
  */
 
 /**
- * Serves as the base class for implementing collection classes.
+ * Skeletal implementation of the { link Gee.Collection} interface.
+ *
+ * Contains common code shared by all collection implementations.
+ *
+ * @see Gee.AbstractList
  */
 public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collection<G> {
 
diff --git a/gee/abstractlist.vala b/gee/abstractlist.vala
index 6f4af8b..3e06fd9 100644
--- a/gee/abstractlist.vala
+++ b/gee/abstractlist.vala
@@ -22,7 +22,12 @@
  */
 
 /**
- * Serves as the base class for implementing list classes.
+ * Skeletal implementation of the { link Gee.List} interface.
+ *
+ * Contains common code shared by all list implementations.
+ *
+ * @see Gee.ArrayList
+ * @see Gee.LinkedList
  */
 public abstract class Gee.AbstractList<G> : Gee.AbstractCollection<G>, List<G> {
 
diff --git a/gee/abstractmap.vala b/gee/abstractmap.vala
index a0192f5..e276ce4 100644
--- a/gee/abstractmap.vala
+++ b/gee/abstractmap.vala
@@ -20,9 +20,15 @@
  * Author:
  * 	Tomaž Vajngerl <quikee gmail com>
  */
- 
- /**
- * Serves as the base class for implementing map classes.
+
+/**
+ * Skeletal implementation of the { link Gee.Map} interface.
+ *
+ * Contains common code shared by all map implementations.
+ *
+ * @see Gee.Map
+ * @see Gee.TreeMap
+ * @see Gee.HashMap
  */
 public abstract class Gee.AbstractMap<K,V> : Object, Map<K,V> {
 
diff --git a/gee/arraylist.vala b/gee/arraylist.vala
index 8eae29b..54c777d 100644
--- a/gee/arraylist.vala
+++ b/gee/arraylist.vala
@@ -25,13 +25,27 @@
 using GLib;
 
 /**
- * Arrays of arbitrary elements which grow automatically as elements are added.
+ * Resizable array implementation of the { link Gee.List} interface.
+ *
+ * The storage array grows automatically when needed.
+ *
+ * This implementation is pretty good for rarely modified data. Because they are
+ * stored in an array this structure does not fit for highly mutable data. For an
+ * alternative implementation see { link Gee.LinkedList}.
+ *
+ * @see Gee.LinkedList
  */
 public class Gee.ArrayList<G> : AbstractList<G> {
+	/**
+	 * @inheritDoc
+	 */
 	public override int size {
 		get { return _size; }
 	}
 
+	/**
+	 * The elements' equality testing function.
+	 */
 	public EqualFunc equal_func { private set; get; }
 
 	private G[] _items = new G[4];
@@ -41,7 +55,7 @@ public class Gee.ArrayList<G> : AbstractList<G> {
 	private int _stamp = 0;
 
 	/**
-	 * Array list implementation constructor.
+	 * Constructs a new, empty array list.
 	 *
 	 * @param equal_func an optional elements equality testing function.
 	 */
diff --git a/gee/collection.vala b/gee/collection.vala
index 2dca0ed..7827a86 100644
--- a/gee/collection.vala
+++ b/gee/collection.vala
@@ -21,8 +21,7 @@
  */
 
 /**
- * Serves as the base interface for implementing collection classes. Defines
- * size, iteration, and modification methods.
+ * A generic collection of objects.
  */
 public interface Gee.Collection<G> : Iterable<G> {
 	/**
diff --git a/gee/functions.vala b/gee/functions.vala
index 9303e0d..7ca0c6c 100644
--- a/gee/functions.vala
+++ b/gee/functions.vala
@@ -24,8 +24,14 @@ using GLib;
 
 namespace Gee {
 
+	/**
+	 * Helper class for equal, hash and compare functions.
+	 */
 	public class Functions {
 
+		private Functions () {
+		}
+
 		/**
 		 * Get a equality testing function for a given type.
 		 *
@@ -73,7 +79,7 @@ namespace Gee {
 	}
 
 	/**
-	 * Compares to arbitrary elements together.
+	 * Compares two arbitrary elements together.
 	 *
 	 * The comparison is done on pointers and not on values behind.
 	 *
diff --git a/gee/hashmap.vala b/gee/hashmap.vala
index 14cdb7b..9d0591f 100644
--- a/gee/hashmap.vala
+++ b/gee/hashmap.vala
@@ -25,17 +25,35 @@
 using GLib;
 
 /**
- * Hashtable implementation of the Map interface.
+ * Hash table implementation of the { link Gee.Map} interface.
+ *
+ * This implementation is better fit for highly heterogenous key values.
+ * In case of high key hashes redundancy or higher amount of data prefer using
+ * tree implementation like { link Gee.TreeMap}.
+ *
+ * @see Gee.TreeMap
  */
 public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
+	/**
+	 * @inheritDoc
+	 */
 	public override int size {
 		get { return _nnodes; }
 	}
 
+	/**
+	 * The keys' hash function.
+	 */
 	public HashFunc key_hash_func { private set; get; }
 
+	/**
+	 * The keys' equality testing function.
+	 */
 	public EqualFunc key_equal_func { private set; get; }
 
+	/**
+	 * The values' equality testing function.
+	 */
 	public EqualFunc value_equal_func { private set; get; }
 
 	private int _array_size;
@@ -48,6 +66,13 @@ public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 	private const int MIN_SIZE = 11;
 	private const int MAX_SIZE = 13845163;
 
+	/**
+	 * Constructs a new, empty hash map.
+	 *
+	 * @param key_hash_func a key hash function.
+	 * @param key_equal_func a key equality testing function.
+	 * @param value_equal_func a value equallity testing function.
+	 */
 	public HashMap (HashFunc? key_hash_func = null, EqualFunc? key_equal_func = null, EqualFunc? value_equal_func = null) {
 		if (key_hash_func == null) {
 			key_hash_func = Functions.get_hash_func_for (typeof (K));
@@ -68,10 +93,16 @@ public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 		_nodes = new Node<K,V>[_array_size];
 	}
 
+	/**
+	 * @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);
 	}
@@ -85,11 +116,17 @@ public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 		return node;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool contains (K key) {
 		Node<K,V>** node = lookup_node (key);
 		return (*node != null);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override V? get (K key) {
 		Node<K,V>* node = (*lookup_node (key));
 		if (node != null) {
@@ -99,6 +136,9 @@ public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 		}
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void set (K key, V value) {
 		Node<K,V>** node = lookup_node (key);
 		if (*node != null) {
@@ -112,6 +152,9 @@ public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 		_stamp++;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override bool remove (K key, out V? value = null) {
 		Node<K,V>** node = lookup_node (key);
 		if (*node != null) {
@@ -135,6 +178,9 @@ public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 		return false;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public override void clear () {
 		for (int i = 0; i < _array_size; i++) {
 			Node<K,V> node = (owned) _nodes[i];
diff --git a/gee/hashset.vala b/gee/hashset.vala
index 17e07c4..d680c45 100644
--- a/gee/hashset.vala
+++ b/gee/hashset.vala
@@ -25,20 +25,29 @@
 using GLib;
 
 /**
- * Hashtable implementation of the Set interface.
+ * Hash table implementation of the { link Gee.Set} interface.
+ *
+ * This implementation is better fit for highly heterogenous values.
+ * In case of high value hashes redundancy or higher amount of data prefer using
+ * tree implementation like { link Gee.TreeSet}.
+ *
+ * @see Gee.TreeSet
  */
 public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
+	/**
+	 * @inheritDoc
+	 */
 	public override int size {
 		get { return _nnodes; }
 	}
 
 	/**
-	 * Hash function.
+	 * The elements' hash function.
 	 */
 	public HashFunc hash_func { private set; get; }
 
 	/**
-	 * Equality testing function.
+	 * The elements' equality testing function.
 	 */
 	public EqualFunc equal_func { private set; get; }
 
@@ -53,7 +62,7 @@ public class Gee.HashSet<G> : AbstractCollection<G>, Set<G> {
 	private const int MAX_SIZE = 13845163;
 
 	/**
-	 * Hash set implementation constructor.
+	 * Constructs a new, empty hash set.
 	 *
 	 * @param hash_func an optional hash function.
 	 * @param equal_func an optional equality testing function.
diff --git a/gee/iterable.vala b/gee/iterable.vala
index 2726325..a59defe 100644
--- a/gee/iterable.vala
+++ b/gee/iterable.vala
@@ -23,8 +23,7 @@
 using GLib;
 
 /**
- * Implemented by classes that support a simple iteration over instances of the
- * collection.
+ * An object that can provide an { link Gee.Iterator}.
  */
 public interface Gee.Iterable<G> : GLib.Object {
 	/**
diff --git a/gee/iterator.vala b/gee/iterator.vala
index 6642a90..4f05b5c 100644
--- a/gee/iterator.vala
+++ b/gee/iterator.vala
@@ -21,8 +21,7 @@
  */
 
 /**
- * Implemented by classes that support a simple iteration over instances of the
- * collection.
+ * An iterator over a collection.
  */
 public interface Gee.Iterator<G> : GLib.Object {
 	/**
diff --git a/gee/linkedlist.vala b/gee/linkedlist.vala
index c3adc20..6ca470b 100644
--- a/gee/linkedlist.vala
+++ b/gee/linkedlist.vala
@@ -25,7 +25,12 @@
  */
 
 /**
- * A Gee.List implementation, using a doubly-linked list.
+ * Doubly-linked list implementation of the { link Gee.List} interface.
+ *
+ * This implementation is pretty well designed for highly mutable data. When
+ * indexed access is privileged prefer using { link Gee.ArrayList}.
+ *
+ * @see Gee.ArrayList
  */
 public class Gee.LinkedList<G> : AbstractList<G> {
 	private int _size = 0;
@@ -34,12 +39,12 @@ public class Gee.LinkedList<G> : AbstractList<G> {
 	private Node? _tail = null;
 
 	/**
-	 * Equality testing between elements function.
+	 * The elements' equality testing function.
 	 */
 	public EqualFunc equal_func { private set; get; }
 
 	/**
-	 * Linked list implementation constructor.
+	 * Constructs a new, empty linked list.
 	 *
 	 * @param equal_func an optional equality testing function.
 	 */
diff --git a/gee/list.vala b/gee/list.vala
index 479cf4c..259ea80 100644
--- a/gee/list.vala
+++ b/gee/list.vala
@@ -21,7 +21,7 @@
  */
 
 /**
- * Represents a collection of items in a well-defined order.
+ * An ordered collection.
  */
 public interface Gee.List<G> : Collection<G> {
 	/**
diff --git a/gee/map.vala b/gee/map.vala
index f4a1983..b3f713a 100644
--- a/gee/map.vala
+++ b/gee/map.vala
@@ -21,7 +21,7 @@
  */
 
 /**
- * A map is a generic collection of key/value pairs.
+ * An object that maps keys to values.
  */
 public interface Gee.Map<K,V> : GLib.Object {
 	/**
diff --git a/gee/readonlycollection.vala b/gee/readonlycollection.vala
index c3496e5..8ef8c69 100644
--- a/gee/readonlycollection.vala
+++ b/gee/readonlycollection.vala
@@ -23,7 +23,13 @@
 using GLib;
 
 /**
- * Represents a read-only collection of items.
+ * Read-only view for { link Gee.Collection} collections.
+ *
+ * This class decorates any class which implements the { link Gee.Collection}
+ * interface by making it read only. Any method which normally modify data will
+ * throw an error.
+ *
+ * @see Gee.Collection
  */
 public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 
@@ -42,7 +48,7 @@ public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 	}
 
 	/**
-	 * Generic collection property.
+	 * The decorated collection.
 	 */
 	public Collection<G> collection {
 		construct { _collection = value; }
@@ -51,7 +57,8 @@ public class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 	private Collection<G> _collection;
 
 	/**
-	 * Read only collection constructor.
+	 * Constructs a read-only collection that mirrors the content of the
+	 * specified collection.
 	 *
 	 * @param collection the collection to decorate (may be null).
 	 */
diff --git a/gee/readonlylist.vala b/gee/readonlylist.vala
index fdedc26..23db056 100644
--- a/gee/readonlylist.vala
+++ b/gee/readonlylist.vala
@@ -23,7 +23,13 @@
 using GLib;
 
 /**
- * Represents a read-only collection of items in a well-defined order.
+ * Read-only view for { link Gee.List} collections.
+ *
+ * This class decorates any class which implements the { link Gee.List}
+ * interface by making it read only. Any method which normally modify data will
+ * throw an error.
+ *
+ * @see Gee.List
  */
 public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 
@@ -42,7 +48,7 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 	}
 
 	/**
-	 * @inheritDoc
+	 * The decorated list.
 	 */
 	public List<G> list {
 		construct { _list = value; }
@@ -51,7 +57,8 @@ public class Gee.ReadOnlyList<G> : Object, Iterable<G>, Collection<G>, List<G> {
 	private List<G> _list;
 
 	/**
-	 * Read only list implementation constrcutor.
+	 * Constructs a read-only set that mirrors the content of the specified
+	 * list.
 	 *
 	 * @param list the list to decorate (may be null).
 	 */
diff --git a/gee/readonlymap.vala b/gee/readonlymap.vala
index e38fb01..d9d7042 100644
--- a/gee/readonlymap.vala
+++ b/gee/readonlymap.vala
@@ -23,27 +23,51 @@
 using GLib;
 
 /**
- * Represents a read-only collection of key/value pairs.
+ * Read-only view for { link Gee.Map} collections.
+ *
+ * This class decorates any class which implements the { link Gee.Map} interface
+ * by making it read only. Any method which normally modify data will throw an
+ * error.
+ *
+ * @see Gee.Map
  */
 public class Gee.ReadOnlyMap<K,V> : Object, Map<K,V> {
+
+	/**
+	 * @inheritDoc
+	 */
 	public int size {
 		get { return _map.size; }
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool is_empty {
 		get { return _map.is_empty; }
 	}
 
+	/**
+	 * The decorated map.
+	 */
 	public Map<K,V> map {
 		construct { _map = value; }
 	}
 
 	private Map<K,V> _map;
 
+	/**
+	 * Constructs a read-only map that mirrors the content of the specified map.
+	 *
+	 * @param map the map to decorate (may be null).
+	 */
 	public ReadOnlyMap (Map<K,V>? map = null) {
 		this.map = map;
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Set<K> get_keys () {
 		if (_map == null) {
 			return new ReadOnlySet<K> ();
@@ -52,6 +76,9 @@ public class Gee.ReadOnlyMap<K,V> : Object, Map<K,V> {
 		return _map.get_keys ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public Collection<V> get_values () {
 		if (_map == null) {
 			return new ReadOnlyCollection<V> ();
@@ -60,6 +87,9 @@ public class Gee.ReadOnlyMap<K,V> : Object, Map<K,V> {
 		return _map.get_values ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains (K key) {
 		if (_map == null) {
 			return false;
@@ -68,6 +98,9 @@ public class Gee.ReadOnlyMap<K,V> : Object, Map<K,V> {
 		return _map.contains (key);
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public new V? get (K key) {
 		if (_map == null) {
 			return null;
@@ -76,26 +109,44 @@ public class Gee.ReadOnlyMap<K,V> : Object, Map<K,V> {
 		return _map.get (key);
 	}
 
+	/**
+	 * Unimplemented method (read only map).
+	 */
 	public new void set (K key, V value) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only map).
+	 */
 	public bool remove (K key, out V? value = null) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only map).
+	 */
 	public void clear () {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only map).
+	 */
 	public void set_all (Map<K,V> map) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * Unimplemented method (read only map).
+	 */
 	public bool remove_all (Map<K,V> map) {
 		assert_not_reached ();
 	}
 
+	/**
+	 * @inheritDoc
+	 */
 	public bool contains_all (Map<K,V> map) {
 		if (_map == null) {
 			return false;
diff --git a/gee/readonlyset.vala b/gee/readonlyset.vala
index 828d0d0..ffe7f60 100644
--- a/gee/readonlyset.vala
+++ b/gee/readonlyset.vala
@@ -23,7 +23,13 @@
 using GLib;
 
 /**
- * Represents a read-only collection of items without duplicates.
+ * Read-only view for { link Gee.Set} collections.
+ *
+ * This class decorates any class which implements the { link Gee.Set} interface
+ * by making it read only. Any method which normally modify data will throw an
+ * error.
+ *
+ * @see Gee.Set
  */
 public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
 
@@ -42,7 +48,7 @@ public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
 	}
 
 	/**
-	 * @inheritDoc
+	 * The decorated set.
 	 */
 	public new Set<G> set {
 		construct { _set = value; }
@@ -51,7 +57,7 @@ public class Gee.ReadOnlySet<G> : Object, Iterable<G>, Collection<G>, Set<G> {
 	private Set<G> _set;
 
 	/**
-	 * Read only set implementation constructor.
+	 * Constructs a read-only set that mirrors the content of the specified set.
 	 *
 	 * @param set the set to decorate.
 	 */
diff --git a/gee/set.vala b/gee/set.vala
index 57b69e3..765db0b 100644
--- a/gee/set.vala
+++ b/gee/set.vala
@@ -21,7 +21,7 @@
  */
 
 /**
- * A set is a collection without duplicates.
+ * A collection without duplicate elements.
  */
 public interface Gee.Set<G> : Collection<G> {
 }
diff --git a/gee/treemap.vala b/gee/treemap.vala
index 25111aa..6bbea61 100644
--- a/gee/treemap.vala
+++ b/gee/treemap.vala
@@ -23,27 +23,37 @@
 using GLib;
 
 /**
- * Left-leaning red-black tree implementation of the Map interface.
+ * Left-leaning red-black tree implementation of the { link Gee.Map} interface.
+ *
+ * This implementation is especially well designed for large quantity of
+ * data. The (balanced) tree implementation insure that the set and get 
+ * methods are in logarithmic complexity.
+ *
+ * @see Gee.HashMap
  */
 public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
+	/**
+	 * @inheritDoc
+	 */
 	public override int size {
 		get { return _size; }
 	}
 
 	/**
-	 * The keys comparator function.
+	 * The keys' comparator function.
 	 */
 	public CompareFunc key_compare_func { private set; get; }
 
 	/**
-	 * The values equality testing function.
+	 * The values' equality testing function.
 	 */
 	public EqualFunc value_equal_func { private set; get; }
 
 	private int _size = 0;
 
 	/**
-	 * Tree map implementation constructor.
+	 * Constructs a new, empty tree map sorted according to the specified
+	 * comparator function.
 	 *
 	 * @param key_compare_func an optional key comparator function.
 	 * @param value_equal_func an optional values equality testing function.
diff --git a/gee/treeset.vala b/gee/treeset.vala
index 61537ff..5af2462 100644
--- a/gee/treeset.vala
+++ b/gee/treeset.vala
@@ -23,22 +23,33 @@
 using GLib;
 
 /**
- * Left-leaning red-black tree implementation of the Set interface.
+ * Left-leaning red-black tree implementation of the { link Gee.Set} interface.
+ *
+ * This implementation is especially well designed for large quantity of
+ * data. The (balanced) tree implementation insure that the set and get
+ * methods are in logarithmic complexity. For a linear implementation see
+ * { link Gee.HashSet}.
+ *
+ * @see Gee.HashSet
  */
 public class Gee.TreeSet<G> : AbstractCollection<G>, Set<G> {
+	/**
+	 * @inheritDoc
+	 */
 	public override int size {
 		get {return _size;}
 	}
 
 	/**
-	 * The elements comparator function.
+	 * The elements' comparator function.
 	 */
 	public CompareFunc compare_func { private set; get; }
 
 	private int _size = 0;
 
 	/**
-	 * Tree set implementation constructor.
+	 * Constructs a new, empty tree set sorted according to the specified
+	 * comparator function.
 	 *
 	 * @param compare_func an optional elements comparator function.
 	 */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]