[libgee] Various documentation enhancements

From: Didier Villevalois <dvillevalois src gnome org>
To: svn-commits-list gnome org
Cc:
Subject: [libgee] Various documentation enhancements
Date: Mon, 28 Sep 2009 14:32:05 +0000 (UTC)
commit 0a9074850f2cc4bb6b7716453bba5fb8b125e753
Author: Didier 'Ptitjes <ptitjes free fr>
Date:   Sat Sep 26 23:32:53 2009 +0200

    Various documentation enhancements

 gee/abstractcollection.vala |    6 ++++--
 gee/abstractlist.vala       |    6 +++---
 gee/abstractmap.vala        |    7 +++----
 gee/abstractmultiset.vala   |    5 ++++-
 gee/abstractqueue.vala      |    4 ++--
 gee/abstractset.vala        |    6 +++---
 gee/arraylist.vala          |    6 +++---
 gee/comparable.vala         |    3 ++-
 gee/functions.vala          |   11 ++++++++++-
 gee/hashmap.vala            |    6 +++---
 gee/hashmultimap.vala       |    2 +-
 gee/hashmultiset.vala       |    2 +-
 gee/hashset.vala            |    6 +++---
 gee/iterable.vala           |    6 +++---
 gee/linkedlist.vala         |    6 +++---
 gee/mapiterator.vala        |   12 +++++++-----
 gee/multimap.vala           |   10 +++++-----
 gee/multiset.vala           |    7 ++++---
 gee/priorityqueue.vala      |    2 +-
 gee/readonlycollection.vala |    6 +++---
 gee/readonlylist.vala       |    6 +++---
 gee/readonlymap.vala        |    6 +++---
 gee/readonlyset.vala        |    6 +++---
 gee/treemap.vala            |    4 ++--
 gee/treemultiset.vala       |    3 ++-
 gee/treeset.vala            |    6 +++---
 26 files changed, 84 insertions(+), 66 deletions(-)
---
diff --git a/gee/abstractcollection.vala b/gee/abstractcollection.vala
index 8ac10fa..88d8240 100644
--- a/gee/abstractcollection.vala
+++ b/gee/abstractcollection.vala
@@ -22,11 +22,13 @@
  */
 
 /**
- * Skeletal implementation of the { link Gee.Collection} interface.
+ * Skeletal implementation of the { link Collection} interface.
  *
  * Contains common code shared by all collection implementations.
  *
- * @see Gee.AbstractList
+ * @see AbstractList
+ * @see AbstractSet
+ * @see AbstractMultiSet
  */
 public abstract class Gee.AbstractCollection<G> : Object, Iterable<G>, Collection<G> {
 
diff --git a/gee/abstractlist.vala b/gee/abstractlist.vala
index d0b189c..65c82b7 100644
--- a/gee/abstractlist.vala
+++ b/gee/abstractlist.vala
@@ -22,12 +22,12 @@
  */
 
 /**
- * Skeletal implementation of the { link Gee.List} interface.
+ * Skeletal implementation of the { link List} interface.
  *
  * Contains common code shared by all list implementations.
  *
- * @see Gee.ArrayList
- * @see Gee.LinkedList
+ * @see ArrayList
+ * @see LinkedList
  */
 public abstract class Gee.AbstractList<G> : Gee.AbstractCollection<G>, List<G> {
 
diff --git a/gee/abstractmap.vala b/gee/abstractmap.vala
index fd350bd..d3cd977 100644
--- a/gee/abstractmap.vala
+++ b/gee/abstractmap.vala
@@ -22,13 +22,12 @@
  */
 
 /**
- * Skeletal implementation of the { link Gee.Map} interface.
+ * Skeletal implementation of the { link Map} interface.
  *
  * Contains common code shared by all map implementations.
  *
- * @see Gee.Map
- * @see Gee.TreeMap
- * @see Gee.HashMap
+ * @see HashMap
+ * @see TreeMap
  */
 public abstract class Gee.AbstractMap<K,V> : Object, Iterable<Map.Entry<K,V>>, Map<K,V> {
 
diff --git a/gee/abstractmultiset.vala b/gee/abstractmultiset.vala
index 2668f24..1b5d444 100644
--- a/gee/abstractmultiset.vala
+++ b/gee/abstractmultiset.vala
@@ -22,7 +22,10 @@
  */
 
 /**
- * Skeletal implementation of the { link Gee.MultiSet} interface.
+ * Skeletal implementation of the { link MultiSet} interface.
+ *
+ * @see HashMultiSet
+ * @see TreeMultiSet
  */
 public abstract class Gee.AbstractMultiSet<G> : AbstractCollection<G>, MultiSet<G> {
 	public override int size {
diff --git a/gee/abstractqueue.vala b/gee/abstractqueue.vala
index 1ec1fa7..ce3fc3d 100644
--- a/gee/abstractqueue.vala
+++ b/gee/abstractqueue.vala
@@ -21,11 +21,11 @@
  */
 
 /**
- * Skeletal implementation of the { link Gee.Queue} interface.
+ * Skeletal implementation of the { link Queue} interface.
  *
  * Contains common code shared by all queue implementations.
  *
- * @see Gee.PriorityQueue
+ * @see PriorityQueue
  */
 public abstract class Gee.AbstractQueue<G> : Gee.AbstractCollection<G>, Queue<G> {
 	/**
diff --git a/gee/abstractset.vala b/gee/abstractset.vala
index 67245af..783d978 100644
--- a/gee/abstractset.vala
+++ b/gee/abstractset.vala
@@ -22,12 +22,12 @@
  */
 
 /**
- * Skeletal implementation of the { link Gee.Set} interface.
+ * Skeletal implementation of the { link Set} interface.
  *
  * Contains common code shared by all set implementations.
  *
- * @see Gee.TreeSet
- * @see Gee.HashSet
+ * @see HashSet
+ * @see TreeSet
  */
 public abstract class Gee.AbstractSet<G> : Gee.AbstractCollection<G>, Set<G> {
 
diff --git a/gee/arraylist.vala b/gee/arraylist.vala
index 420dcee..474bdcb 100644
--- a/gee/arraylist.vala
+++ b/gee/arraylist.vala
@@ -27,15 +27,15 @@
 using GLib;
 
 /**
- * Resizable array implementation of the { link Gee.List} interface.
+ * Resizable array implementation of the { link 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}.
+ * alternative implementation see { link LinkedList}.
  *
- * @see Gee.LinkedList
+ * @see LinkedList
  */
 public class Gee.ArrayList<G> : AbstractList<G> {
 	/**
diff --git a/gee/comparable.vala b/gee/comparable.vala
index 5d848d8..01e9a5e 100644
--- a/gee/comparable.vala
+++ b/gee/comparable.vala
@@ -21,7 +21,8 @@
  */
 
 /**
- * This interface defines a total ordering among each class implementing it.
+ * This interface defines a total ordering among instances of each class
+ * implementing it.
  */
 public interface Gee.Comparable<G> : Object {
 	/**
diff --git a/gee/functions.vala b/gee/functions.vala
index 02267dc..6c7a138 100644
--- a/gee/functions.vala
+++ b/gee/functions.vala
@@ -26,7 +26,16 @@ using GLib;
 namespace Gee {
 
 	/**
-	 * Helper class for equal, hash and compare functions.
+	 * Helpers for equal, hash and compare functions.
+	 *
+	 * With those functions, you can retrieve the equal, hash and compare
+	 * functions that best match your element, key or value types. Supported
+	 * types are (non-boxed) primitive, string and `Object` types.
+	 *
+	 * A special care is taken for classes inheriting from the
+	 * { link Comparable} interface. For such types, an appropriate compare
+	 * function is returned that calls { link Comparable.compare_to}.
+	 *
 	 */
 	namespace Functions {
 
diff --git a/gee/hashmap.vala b/gee/hashmap.vala
index 34b19f7..6a6c7b2 100644
--- a/gee/hashmap.vala
+++ b/gee/hashmap.vala
@@ -25,13 +25,13 @@
 using GLib;
 
 /**
- * Hash table implementation of the { link Gee.Map} interface.
+ * Hash table implementation of the { link 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}.
+ * tree implementation like { link TreeMap}.
  *
- * @see Gee.TreeMap
+ * @see TreeMap
  */
 public class Gee.HashMap<K,V> : Gee.AbstractMap<K,V> {
 	/**
diff --git a/gee/hashmultimap.vala b/gee/hashmultimap.vala
index 25fa8ac..3e4258a 100644
--- a/gee/hashmultimap.vala
+++ b/gee/hashmultimap.vala
@@ -21,7 +21,7 @@
  */
 
 /**
- * A MultiMap implemented using a HashMap of Sets
+ * Hash table implementation of the { link MultiMap} interface.
  */
 public class Gee.HashMultiMap<K,V> : GLib.Object, MultiMap<K,V> {
 	public int size {
diff --git a/gee/hashmultiset.vala b/gee/hashmultiset.vala
index a5c6227..bcfb347 100644
--- a/gee/hashmultiset.vala
+++ b/gee/hashmultiset.vala
@@ -21,7 +21,7 @@
  */
 
 /**
- * A hash based implementation of the { link Gee.MultiSet} interface.
+ * Hash table implementation of the { link MultiSet} interface.
  */
 public class Gee.HashMultiSet<G> : AbstractMultiSet<G> {
 	public HashFunc hash_func {
diff --git a/gee/hashset.vala b/gee/hashset.vala
index 2dc97ed..d34a94a 100644
--- a/gee/hashset.vala
+++ b/gee/hashset.vala
@@ -25,13 +25,13 @@
 using GLib;
 
 /**
- * Hash table implementation of the { link Gee.Set} interface.
+ * Hash table implementation of the { link 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}.
+ * tree implementation like { link TreeSet}.
  *
- * @see Gee.TreeSet
+ * @see TreeSet
  */
 public class Gee.HashSet<G> : AbstractSet<G> {
 	/**
diff --git a/gee/iterable.vala b/gee/iterable.vala
index a59defe..bdb3611 100644
--- a/gee/iterable.vala
+++ b/gee/iterable.vala
@@ -23,7 +23,7 @@
 using GLib;
 
 /**
- * An object that can provide an { link Gee.Iterator}.
+ * An object that can provide an { link Iterator}.
  */
 public interface Gee.Iterable<G> : GLib.Object {
 	/**
@@ -32,10 +32,10 @@ public interface Gee.Iterable<G> : GLib.Object {
 	public abstract Type element_type { get; }
 
 	/**
-	 * Returns a Iterator that can be used for simple iteration over a
+	 * Returns a { link Iterator} that can be used for simple iteration over a
 	 * collection.
 	 *
-	 * @return a Iterator that can be used for simple iteration over a
+	 * @return a { link Iterator} that can be used for simple iteration over a
 	 *         collection
 	 */
 	public abstract Iterator<G> iterator ();
diff --git a/gee/linkedlist.vala b/gee/linkedlist.vala
index efa2912..f01ea47 100644
--- a/gee/linkedlist.vala
+++ b/gee/linkedlist.vala
@@ -25,12 +25,12 @@
  */
 
 /**
- * Doubly-linked list implementation of the { link Gee.List} interface.
+ * Doubly-linked list implementation of the { link List} interface.
  *
  * This implementation is pretty well designed for highly mutable data. When
- * indexed access is privileged prefer using { link Gee.ArrayList}.
+ * indexed access is privileged prefer using { link ArrayList}.
  *
- * @see Gee.ArrayList
+ * @see ArrayList
  */
 public class Gee.LinkedList<G> : AbstractList<G>, Queue<G>, Deque<G> {
 	private int _size = 0;
diff --git a/gee/mapiterator.vala b/gee/mapiterator.vala
index edb9b75..230cd77 100644
--- a/gee/mapiterator.vala
+++ b/gee/mapiterator.vala
@@ -27,9 +27,10 @@
  * except before the first call to { link next} or { link first}, or, when an
  * item has been removed, until the next call to { link next} or { link first}.
  *
- * Please note that when the iterator is out of track, neither { link get} nor
- * { link remove} are defined and both will fail. After the next call to
- * { link next} or { link first}, they will be defined again.
+ * Please note that when the iterator is out of track, neither { link get_key},
+ * { link get_value}, { link set_value} nor { link unset} are defined and all
+ * will fail. After the next call to { link next} or { link first}, they will
+ * be defined again.
  */
 public interface Gee.MapIterator<K,V> : GLib.Object {
 	/**
@@ -76,8 +77,9 @@ public interface Gee.MapIterator<K,V> : GLib.Object {
 
 	/**
 	 * Unsets the current entry in the iteration. The cursor is set in an
-	 * in-between state. Both { link get} and { link unset} will fail until
-	 * the next move of the cursor (calling { link next} or { link first}).
+	 * in-between state. { link get_key}, { link get_value}, { link set_value}
+	 * and { link unset} will fail until the next move of the cursor (calling
+	 * { link next} or { link first}).
 	 */
 	public abstract void unset ();
 }
diff --git a/gee/multimap.vala b/gee/multimap.vala
index 757b535..4bb40a7 100644
--- a/gee/multimap.vala
+++ b/gee/multimap.vala
@@ -21,8 +21,7 @@
  */
 
 /**
- * A MultiMap is a map where you can associate multiple values to the
- * same key.
+ * A map with multiple values per key.
  */
 public interface Gee.MultiMap<K,V> : GLib.Object {
 	/**
@@ -83,14 +82,15 @@ public interface Gee.MultiMap<K,V> : GLib.Object {
 	 * @param key   the key to remove from the map
 	 * @param value the value to remove from the map
 	 *
-	 * @return    true if the map has been changed, false otherwise
+	 * @return      true if the map has been changed, false otherwise
 	 */
 	public abstract bool remove (K key, V value);
 
 	/**
-	 * Removes the specified key and all the associated values from this multimap.
+	 * Removes the specified key and all the associated values from this
+	 * multimap.
 	 *
-	 * @param key   the key to remove from the map
+	 * @param key the key to remove from the map
 	 *
 	 * @return    true if the map has been changed, false otherwise
 	 */
diff --git a/gee/multiset.vala b/gee/multiset.vala
index 85d44be..0c169e9 100644
--- a/gee/multiset.vala
+++ b/gee/multiset.vala
@@ -21,14 +21,15 @@
  */
 
 /**
- * A MultiSet is a collection allowing duplicates.
+ * A collection with duplicate elements.
  */
 public interface Gee.MultiSet<G> : Collection<G> {
 	/**
-	 * Returns the number of occurences of an item in this MultiSet
+	 * Returns the number of occurences of an item in this multiset.
 	 *
 	 * @param item the item to count occurences of
-	 * @return the number of occurences of the item in this multiset.
+	 *
+	 * @return     the number of occurences of the item in this multiset.
 	 */
 	public abstract int count (G item);
 }
diff --git a/gee/priorityqueue.vala b/gee/priorityqueue.vala
index 3c1661f..04f7029 100644
--- a/gee/priorityqueue.vala
+++ b/gee/priorityqueue.vala
@@ -21,7 +21,7 @@
  */
 
 /**
- * A unbounded priority queue implementation of the { link Gee.Queue}.
+ * Relaxed fibonacci heap priority queue implementation of the { link Queue}.
  *
  * The elements of the priority queue are ordered according to their natural
  * ordering, or by a compare_func provided at queue construction time. A
diff --git a/gee/readonlycollection.vala b/gee/readonlycollection.vala
index 79678cf..0c1dfe2 100644
--- a/gee/readonlycollection.vala
+++ b/gee/readonlycollection.vala
@@ -23,13 +23,13 @@
 using GLib;
 
 /**
- * Read-only view for { link Gee.Collection} collections.
+ * Read-only view for { link Collection} collections.
  *
- * This class decorates any class which implements the { link Gee.Collection}
+ * This class decorates any class which implements the { link Collection}
  * interface by making it read only. Any method which normally modify data will
  * throw an error.
  *
- * @see Gee.Collection
+ * @see Collection
  */
 internal class Gee.ReadOnlyCollection<G> : Object, Iterable<G>, Collection<G> {
 
diff --git a/gee/readonlylist.vala b/gee/readonlylist.vala
index b32c030..8ccb2cf 100644
--- a/gee/readonlylist.vala
+++ b/gee/readonlylist.vala
@@ -23,13 +23,13 @@
 using GLib;
 
 /**
- * Read-only view for { link Gee.List} collections.
+ * Read-only view for { link List} collections.
  *
- * This class decorates any class which implements the { link Gee.List}
+ * This class decorates any class which implements the { link List}
  * interface by making it read only. Any method which normally modify data will
  * throw an error.
  *
- * @see Gee.List
+ * @see List
  */
 internal class Gee.ReadOnlyList<G> : Gee.ReadOnlyCollection<G>, List<G> {
 
diff --git a/gee/readonlymap.vala b/gee/readonlymap.vala
index 13bc280..87b0ffc 100644
--- a/gee/readonlymap.vala
+++ b/gee/readonlymap.vala
@@ -23,13 +23,13 @@
 using GLib;
 
 /**
- * Read-only view for { link Gee.Map} collections.
+ * Read-only view for { link Map} collections.
  *
- * This class decorates any class which implements the { link Gee.Map} interface
+ * This class decorates any class which implements the { link Map} interface
  * by making it read only. Any method which normally modify data will throw an
  * error.
  *
- * @see Gee.Map
+ * @see Map
  */
 internal class Gee.ReadOnlyMap<K,V> : Object, Iterable<Map.Entry<K,V>>, Map<K,V> {
 
diff --git a/gee/readonlyset.vala b/gee/readonlyset.vala
index 8b51503..71fd2fb 100644
--- a/gee/readonlyset.vala
+++ b/gee/readonlyset.vala
@@ -23,13 +23,13 @@
 using GLib;
 
 /**
- * Read-only view for { link Gee.Set} collections.
+ * Read-only view for { link Set} collections.
  *
- * This class decorates any class which implements the { link Gee.Set} interface
+ * This class decorates any class which implements the { link Set} interface
  * by making it read only. Any method which normally modify data will throw an
  * error.
  *
- * @see Gee.Set
+ * @see Set
  */
 internal class Gee.ReadOnlySet<G> : Gee.ReadOnlyCollection<G>, Set<G> {
 
diff --git a/gee/treemap.vala b/gee/treemap.vala
index 6bd5b08..97b4ef1 100644
--- a/gee/treemap.vala
+++ b/gee/treemap.vala
@@ -23,13 +23,13 @@
 using GLib;
 
 /**
- * Left-leaning red-black tree implementation of the { link Gee.Map} interface.
+ * Left-leaning red-black tree implementation of the { link 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
+ * @see HashMap
  */
 public class Gee.TreeMap<K,V> : Gee.AbstractMap<K,V> {
 	/**
diff --git a/gee/treemultiset.vala b/gee/treemultiset.vala
index 0feebe9..f940a25 100644
--- a/gee/treemultiset.vala
+++ b/gee/treemultiset.vala
@@ -21,7 +21,8 @@
  */
 
 /**
- * A tree based implementation of the { link Gee.MultiSet} interface.
+ * Left-leaning red-black tree implementation of the { link MultiSet}
+ * interface.
  */
 public class Gee.TreeMultiSet<G> : AbstractMultiSet<G> {
 	public CompareFunc compare_func {
diff --git a/gee/treeset.vala b/gee/treeset.vala
index 4a4c8f0..6d6b9a8 100644
--- a/gee/treeset.vala
+++ b/gee/treeset.vala
@@ -23,14 +23,14 @@
 using GLib;
 
 /**
- * Left-leaning red-black tree implementation of the { link Gee.Set} interface.
+ * Left-leaning red-black tree implementation of the { link 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}.
+ * { link HashSet}.
  *
- * @see Gee.HashSet
+ * @see HashSet
  */
 public class Gee.TreeSet<G> : AbstractSet<G>, SortedSet<G> {
 	/**
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]