From 0a9074850f2cc4bb6b7716453bba5fb8b125e753 Mon Sep 17 00:00:00 2001 From: Didier 'Ptitjes Date: Sat, 26 Sep 2009 23:32:53 +0200 Subject: [PATCH] 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 : Object, Iterable, Collection { 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 : Gee.AbstractCollection, List { 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 : Object, Iterable>, Map { 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 : AbstractCollection, MultiSet { 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 : Gee.AbstractCollection, Queue { /** 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 : Gee.AbstractCollection, Set { 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 : AbstractList { /** 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 : 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 : Gee.AbstractMap { /** 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 : GLib.Object, MultiMap { 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 : AbstractMultiSet { 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 : AbstractSet { /** 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 : GLib.Object { /** @@ -32,10 +32,10 @@ public interface Gee.Iterable : 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 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 : AbstractList, Queue, Deque { 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 : GLib.Object { /** @@ -76,8 +77,9 @@ public interface Gee.MapIterator : 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 : GLib.Object { /** @@ -83,14 +82,15 @@ public interface Gee.MultiMap : 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 : Collection { /** - * 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 : Object, Iterable, Collection { 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 : Gee.ReadOnlyCollection, List { 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 : Object, Iterable>, Map { 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 : Gee.ReadOnlyCollection, Set { 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 : Gee.AbstractMap { /** 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 : AbstractMultiSet { 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 : AbstractSet, SortedSet { /** -- 2.7.4