Index: lemon/maps.h
===================================================================
--- lemon/maps.h	(revision 768)
+++ lemon/maps.h	(revision 769)
@@ -57,5 +57,5 @@
   /// but data written to it is not required (i.e. it will be sent to
   /// <tt>/dev/null</tt>).
-  /// It conforms the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
+  /// It conforms to the \ref concepts::ReadWriteMap "ReadWriteMap" concept.
   ///
   /// \sa ConstMap
@@ -90,5 +90,5 @@
   ///
   /// In other aspects it is equivalent to \c NullMap.
-  /// So it conforms the \ref concepts::ReadWriteMap "ReadWriteMap"
+  /// So it conforms to the \ref concepts::ReadWriteMap "ReadWriteMap"
   /// concept, but it absorbs the data written to it.
   ///
@@ -159,5 +159,5 @@
   ///
   /// In other aspects it is equivalent to \c NullMap.
-  /// So it conforms the \ref concepts::ReadWriteMap "ReadWriteMap"
+  /// So it conforms to the \ref concepts::ReadWriteMap "ReadWriteMap"
   /// concept, but it absorbs the data written to it.
   ///
@@ -233,5 +233,5 @@
   /// It can be used with some data structures, for example
   /// \c UnionFind, \c BinHeap, when the used items are small
-  /// integers. This map conforms the \ref concepts::ReferenceMap
+  /// integers. This map conforms to the \ref concepts::ReferenceMap
   /// "ReferenceMap" concept.
   ///
@@ -341,5 +341,5 @@
   /// stored actually. This value can be different from the default
   /// contructed value (i.e. \c %Value()).
-  /// This type conforms the \ref concepts::ReferenceMap "ReferenceMap"
+  /// This type conforms to the \ref concepts::ReferenceMap "ReferenceMap"
   /// concept.
   ///
@@ -707,5 +707,5 @@
   /// The \c Key type of it is inherited from \c M and the \c Value
   /// type is \c V.
-  /// This type conforms the \ref concepts::ReadMap "ReadMap" concept.
+  /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
   ///
   /// The simplest way of using this map is through the convertMap()
@@ -1866,7 +1866,9 @@
   public:
 
-    /// \brief This class represents the inverse of its owner (IdMap).
-    ///
-    /// This class represents the inverse of its owner (IdMap).
+    /// \brief The inverse map type of IdMap.
+    ///
+    /// The inverse map type of IdMap. The subscript operator gives back
+    /// an item by its id.
+    /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
     /// \see inverse()
     class InverseMap {
@@ -1883,7 +1885,7 @@
       explicit InverseMap(const IdMap& map) : _graph(map._graph) {}
 
-      /// \brief Gives back the given item from its id.
+      /// \brief Gives back an item by its id.
       ///
-      /// Gives back the given item from its id.
+      /// Gives back an item by its id.
       Item operator[](int id) const { return _graph->fromId(id, Item());}
 
@@ -1904,6 +1906,15 @@
   /// It wraps a standard graph map (\c NodeMap, \c ArcMap or \c EdgeMap)
   /// and if a key is set to a new value, then stores it in the inverse map.
-  /// The values of the map can be accessed
-  /// with stl compatible forward iterator.
+  /// The graph items can be accessed by their values either using
+  /// \c InverseMap or \c operator()(), and the values of the map can be
+  /// accessed with an STL compatible forward iterator (\c ValueIterator).
+  /// 
+  /// This map is intended to be used when all associated values are
+  /// different (the map is actually invertable) or there are only a few
+  /// items with the same value.
+  /// Otherwise consider to use \c IterableValueMap, which is more 
+  /// suitable and more efficient for such cases. It provides iterators
+  /// to traverse the items with the same associated value, however
+  /// it does not have \c InverseMap.
   ///
   /// This type is not reference map, so it cannot be modified with
@@ -1946,5 +1957,5 @@
     /// \brief Forward iterator for values.
     ///
-    /// This iterator is an stl compatible forward
+    /// This iterator is an STL compatible forward
     /// iterator on the values of the map. The values can
     /// be accessed in the <tt>[beginValue, endValue)</tt> range.
@@ -1959,7 +1970,10 @@
     public:
 
+      /// Constructor
       ValueIterator() {}
 
+      /// \e
       ValueIterator& operator++() { ++it; return *this; }
+      /// \e
       ValueIterator operator++(int) {
         ValueIterator tmp(*this);
@@ -1968,8 +1982,12 @@
       }
 
+      /// \e
       const Value& operator*() const { return it->first; }
+      /// \e
       const Value* operator->() const { return &(it->first); }
 
+      /// \e
       bool operator==(ValueIterator jt) const { return it == jt.it; }
+      /// \e
       bool operator!=(ValueIterator jt) const { return it != jt.it; }
 
@@ -1980,5 +1998,5 @@
     /// \brief Returns an iterator to the first value.
     ///
-    /// Returns an stl compatible iterator to the
+    /// Returns an STL compatible iterator to the
     /// first value of the map. The values of the
     /// map can be accessed in the <tt>[beginValue, endValue)</tt>
@@ -1990,5 +2008,5 @@
     /// \brief Returns an iterator after the last value.
     ///
-    /// Returns an stl compatible iterator after the
+    /// Returns an STL compatible iterator after the
     /// last value of the map. The values of the
     /// map can be accessed in the <tt>[beginValue, endValue)</tt>
@@ -2091,8 +2109,10 @@
   public:
 
-    /// \brief The inverse map type.
-    ///
-    /// The inverse of this map. The subscript operator of the map
-    /// gives back the item that was last assigned to the value.
+    /// \brief The inverse map type of CrossRefMap.
+    ///
+    /// The inverse map type of CrossRefMap. The subscript operator gives
+    /// back an item by its value.
+    /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
+    /// \see inverse()
     class InverseMap {
     public:
@@ -2121,7 +2141,7 @@
     };
 
-    /// \brief It gives back the read-only inverse map.
-    ///
-    /// It gives back the read-only inverse map.
+    /// \brief Gives back the inverse of the map.
+    ///
+    /// Gives back the inverse of the CrossRefMap.
     InverseMap inverse() const {
       return InverseMap(*this);
@@ -2273,14 +2293,14 @@
     }
 
-    /// \brief Gives back the \e RangeId of the item
-    ///
-    /// Gives back the \e RangeId of the item.
+    /// \brief Gives back the \e range \e id of the item
+    ///
+    /// Gives back the \e range \e id of the item.
     int operator[](const Item& item) const {
       return Map::operator[](item);
     }
 
-    /// \brief Gives back the item belonging to a \e RangeId
-    ///
-    /// Gives back the item belonging to a \e RangeId.
+    /// \brief Gives back the item belonging to a \e range \e id
+    ///
+    /// Gives back the item belonging to the given \e range \e id.
     Item operator()(int id) const {
       return _inv_map[id];
@@ -2296,5 +2316,7 @@
     /// \brief The inverse map type of RangeIdMap.
     ///
-    /// The inverse map type of RangeIdMap.
+    /// The inverse map type of RangeIdMap. The subscript operator gives
+    /// back an item by its \e range \e id.
+    /// This type conforms to the \ref concepts::ReadMap "ReadMap" concept.
     class InverseMap {
     public:
@@ -2314,5 +2336,5 @@
       ///
       /// Subscript operator. It gives back the item
-      /// that the descriptor currently belongs to.
+      /// that the given \e range \e id currently belongs to.
       Value operator[](const Key& key) const {
         return _inverted(key);
@@ -2332,5 +2354,5 @@
     /// \brief Gives back the inverse of the map.
     ///
-    /// Gives back the inverse of the map.
+    /// Gives back the inverse of the RangeIdMap.
     const InverseMap inverse() const {
       return InverseMap(*this);
@@ -2343,8 +2365,8 @@
   /// \c bool value for graph items (\c Node, \c Arc or \c Edge).
   /// For both \c true and \c false values it is possible to iterate on
-  /// the keys.
+  /// the keys mapped to the value.
   ///
   /// This type is a reference map, so it can be modified with the
-  /// subscription operator.
+  /// subscript operator.
   ///
   /// \tparam GR The graph type.
@@ -2712,6 +2734,11 @@
   /// mapped to the value.
   ///
+  /// This map is intended to be used with small integer values, for which
+  /// it is efficient, and supports iteration only for non-negative values.
+  /// If you need large values and/or iteration for negative integers,
+  /// consider to use \ref IterableValueMap instead.
+  ///
   /// This type is a reference map, so it can be modified with the
-  /// subscription operator.
+  /// subscript operator.
   ///
   /// \note The size of the data structure depends on the largest
@@ -2993,16 +3020,18 @@
   /// \brief Dynamic iterable map for comparable values.
   ///
-  /// This class provides a special graph map type which can store an
+  /// This class provides a special graph map type which can store a
   /// comparable value for graph items (\c Node, \c Arc or \c Edge).
   /// For each value it is possible to iterate on the keys mapped to
-  /// the value.
-  ///
-  /// The map stores for each value a linked list with
-  /// the items which mapped to the value, and the values are stored
-  /// in balanced binary tree. The values of the map can be accessed
-  /// with stl compatible forward iterator.
+  /// the value (\c ItemIt), and the values of the map can be accessed
+  /// with an STL compatible forward iterator (\c ValueIterator).
+  /// The map stores a linked list for each value, which contains
+  /// the items mapped to the value, and the used values are stored
+  /// in balanced binary tree (\c std::map).
+  ///
+  /// \ref IterableBoolMap and \ref IterableIntMap are similar classes
+  /// specialized for \c bool and \c int values, respectively.
   ///
   /// This type is not reference map, so it cannot be modified with
-  /// the subscription operator.
+  /// the subscript operator.
   ///
   /// \tparam GR The graph type.
@@ -3080,5 +3109,5 @@
     /// \brief Forward iterator for values.
     ///
-    /// This iterator is an stl compatible forward
+    /// This iterator is an STL compatible forward
     /// iterator on the values of the map. The values can
     /// be accessed in the <tt>[beginValue, endValue)</tt> range.
@@ -3091,7 +3120,10 @@
     public:
 
+      /// Constructor
       ValueIterator() {}
 
+      /// \e
       ValueIterator& operator++() { ++it; return *this; }
+      /// \e
       ValueIterator operator++(int) {
         ValueIterator tmp(*this);
@@ -3100,8 +3132,12 @@
       }
 
+      /// \e
       const Value& operator*() const { return it->first; }
+      /// \e
       const Value* operator->() const { return &(it->first); }
 
+      /// \e
       bool operator==(ValueIterator jt) const { return it == jt.it; }
+      /// \e
       bool operator!=(ValueIterator jt) const { return it != jt.it; }
 
@@ -3112,5 +3148,5 @@
     /// \brief Returns an iterator to the first value.
     ///
-    /// Returns an stl compatible iterator to the
+    /// Returns an STL compatible iterator to the
     /// first value of the map. The values of the
     /// map can be accessed in the <tt>[beginValue, endValue)</tt>
@@ -3122,5 +3158,5 @@
     /// \brief Returns an iterator after the last value.
     ///
-    /// Returns an stl compatible iterator after the
+    /// Returns an STL compatible iterator after the
     /// last value of the map. The values of the
     /// map can be accessed in the <tt>[beginValue, endValue)</tt>
