# HG changeset patch
# User kpeter
# Date 1202215265 0
# Node ID 3250756f5add066e310cb85de7e4c2a21b0ad7b3
# Parent  5841132a89fdefc2ed8d57ef4c2208897fb4002e
Several doc improvements and fixes in maps.h and concepts/maps.h.

diff -r 5841132a89fd -r 3250756f5add lemon/concepts/maps.h
--- a/lemon/concepts/maps.h	Tue Feb 05 11:24:32 2008 +0000
+++ b/lemon/concepts/maps.h	Tue Feb 05 12:41:05 2008 +0000
@@ -34,17 +34,23 @@
     /// @{
 
     /// Readable map concept
+
+    /// Readable map concept.
+    ///
     template<typename K, typename T>
     class ReadMap
     {
     public:
-      /// Map's key type.
+      /// The key type of the map.
       typedef K Key;    
-      /// Map's value type. (The type of objects associated with the keys).
+      /// The value type of the map. (The type of objects associated with the keys).
       typedef T Value;
 
-      // \bug Value don't need to be default constructible.
       /// Returns the value associated with a key.
+
+      /// Returns the value associated with a key.
+      /// \bug Value shouldn't need to be default constructible.
+      ///
       Value operator[](const Key &) const {return Value();}
 
       template<typename _ReadMap>
@@ -69,13 +75,16 @@
 
 
     /// Writable map concept
+    
+    /// Writable map concept.
+    ///
     template<typename K, typename T>
     class WriteMap
     {
     public:
-      /// Map's key type.
+      /// The key type of the map.
       typedef K Key;    
-      /// Map's value type. (The type of objects associated with the keys).
+      /// The value type of the map. (The type of objects associated with the keys).
       typedef T Value;
 
       /// Sets the value associated with a key.
@@ -105,15 +114,18 @@
       };
     };
 
-    ///Read/Writable map concept
+    /// Read/writable map concept
+    
+    /// Read/writable map concept.
+    ///
     template<typename K, typename T>
     class ReadWriteMap : public ReadMap<K,T>,
-			    public WriteMap<K,T>
+			 public WriteMap<K,T>
     {
     public:
-      /// Map's key type.
+      /// The key type of the map.
       typedef K Key;    
-      /// Map's value type. (The type of objects associated with the keys).
+      /// The value type of the map. (The type of objects associated with the keys).
       typedef T Value;
 
       /// Returns the value associated with a key.
@@ -132,39 +144,41 @@
   
   
     ///Dereferable map concept
+    
+    /// Dereferable map concept.
+    ///
+    /// \todo Rethink this concept.
     template<typename K, typename T, typename R, typename CR>
     class ReferenceMap : public ReadWriteMap<K,T>
     {
     public:
       /// Tag for reference maps.
       typedef True ReferenceMapTag;
-      /// Map's key type.
+      /// The key type of the map.
       typedef K Key;    
-      /// Map's value type. (The type of objects associated with the keys).
+      /// The value type of the map. (The type of objects associated with the keys).
       typedef T Value;
-      /// Map's reference type.
+      /// The reference type of the map.
       typedef R Reference;
-      /// Map's const reference type.
+      /// The const reference type of the map.
       typedef CR ConstReference;
 
     protected:
       Value tmp;
     public:
 
-      ///Returns a reference to the value associated to a key.
+      ///Returns a reference to the value associated with a key.
       Reference operator[](const Key &) { return tmp; }
-      ///Returns a const reference to the value associated to a key.
-      ConstReference operator[](const Key &) const
-      { return tmp; }
+      ///Returns a const reference to the value associated with a key.
+      ConstReference operator[](const Key &) const { return tmp; }
       /// Sets the value associated with a key.
       void set(const Key &k,const Value &t) { operator[](k)=t; }
 
-      // \todo rethink this concept
       template<typename _ReferenceMap>
-      struct ReferenceMapConcept {
+      struct Constraints {
 
 	void constraints() {
-	  checkConcept<ReadWriteMap, _ReferenceMap >();
+	  checkConcept<ReadWriteMap<K, T>, _ReferenceMap >();
 	  m[key] = val;
 	  val  = m[key];
 	  m[key] = ref;
@@ -177,10 +191,10 @@
 
 	typename _ReferenceMap::Key& own_key;
 	typename _ReferenceMap::Value& own_val;
-	typename _ReferenceMap::Reference& own_ref;
+	typename _ReferenceMap::Reference own_ref;
 	Key& key;
 	Value& val;
-	Reference& ref;
+	Reference ref;
 	_ReferenceMap& m;
       };
     };
@@ -188,5 +202,7 @@
     // @}
 
   } //namespace concepts
+
 } //namespace lemon
+
 #endif // LEMON_CONCEPT_MAPS_H
diff -r 5841132a89fd -r 3250756f5add lemon/maps.h
--- a/lemon/maps.h	Tue Feb 05 11:24:32 2008 +0000
+++ b/lemon/maps.h	Tue Feb 05 12:41:05 2008 +0000
@@ -44,17 +44,18 @@
   template<typename K, typename T>
   class MapBase {
   public:
-    ///\e
+    /// The key type of the map.
     typedef K Key;
-    ///\e
+    /// The value type of the map. (The type of objects associated with the keys).
     typedef T Value;
   };
 
   /// Null map. (a.k.a. DoNothingMap)
 
-  /// If you have to provide a map only for its type definitions,
-  /// or if you have to provide a writable map, but
-  /// data written to it will sent to <tt>/dev/null</tt>...
+  /// This map can be used if you have to provide a map only for
+  /// its type definitions, or if you have to provide a writable map, 
+  /// but data written to it is not required (i.e. it will be sent to 
+  /// <tt>/dev/null</tt>).
   template<typename K, typename T>
   class NullMap : public MapBase<K, T> {
   public:
@@ -68,6 +69,10 @@
     void set(const K&, const T&) {}
   };
 
+  ///Returns a \c NullMap class
+
+  ///This function just returns a \c NullMap class.
+  ///\relates NullMap
   template <typename K, typename V> 
   NullMap<K, V> nullMap() {
     return NullMap<K, V>();
@@ -76,8 +81,9 @@
 
   /// Constant map.
 
-  /// This is a readable map which assigns a specified value to each key.
-  /// In other aspects it is equivalent to the \c NullMap.
+  /// This is a \ref concepts::ReadMap "readable" map which assigns a 
+  /// specified value to each key.
+  /// In other aspects it is equivalent to \c NullMap.
   template<typename K, typename T>
   class ConstMap : public MapBase<K, T> {
   private:
@@ -90,13 +96,15 @@
 
     /// Default constructor
 
+    /// Default constructor.
     /// The value of the map will be uninitialized. 
     /// (More exactly it will be default constructed.)
     ConstMap() {}
-    ///\e
+    
+    /// Constructor with specified initial value
 
-    /// \param _v The initial value of the map.
-    ///
+    /// Constructor with specified initial value.
+    /// \param _v is the initial value of the map.
     ConstMap(const T &_v) : v(_v) {}
     
     ///\e
@@ -131,8 +139,9 @@
 
   /// Constant map with inlined constant value.
 
-  /// This is a readable map which assigns a specified value to each key.
-  /// In other aspects it is equivalent to the \c NullMap.
+  /// This is a \ref concepts::ReadMap "readable" map which assigns a 
+  /// specified value to each key.
+  /// In other aspects it is equivalent to \c NullMap.
   template<typename K, typename V, V v>
   class ConstMap<K, Const<V, v> > : public MapBase<K, V> {
   public:
@@ -147,7 +156,7 @@
     void set(const K&, const V&) { }
   };
 
-  ///Returns a \c ConstMap class
+  ///Returns a \c ConstMap class with inlined value
 
   ///This function just returns a \c ConstMap class with inlined value.
   ///\relates ConstMap
@@ -156,25 +165,28 @@
     return ConstMap<K, Const<V, v> >();
   }
 
-  ///Map based on std::map
+  ///Map based on \c std::map
 
-  ///This is essentially a wrapper for \c std::map. With addition that
+  ///This is essentially a wrapper for \c std::map with addition that
   ///you can specify a default value different from \c Value() .
+  ///It meets the \ref concepts::ReferenceMap "ReferenceMap" concept.
   template <typename K, typename T, typename Compare = std::less<K> >
-  class StdMap {
+  class StdMap : public MapBase<K, T> {
     template <typename K1, typename T1, typename C1>
     friend class StdMap;
   public:
 
+    typedef MapBase<K, T> Parent;
+    ///Key type
+    typedef typename Parent::Key Key;
+    ///Value type
+    typedef typename Parent::Value Value;
+    ///Reference Type
+    typedef T& Reference;
+    ///Const reference type
+    typedef const T& ConstReference;
+
     typedef True ReferenceMapTag;
-    ///\e
-    typedef K Key;
-    ///\e
-    typedef T Value;
-    ///\e
-    typedef T& Reference;
-    ///\e
-    typedef const T& ConstReference;
 
   private:
     
@@ -186,13 +198,13 @@
 
     /// Constructor with specified default value
     StdMap(const T& value = T()) : _value(value) {}
-    /// \brief Constructs the map from an appropriate std::map, and explicitly
-    /// specifies a default value.
+    /// \brief Constructs the map from an appropriate \c std::map, and 
+    /// explicitly specifies a default value.
     template <typename T1, typename Comp1>
     StdMap(const std::map<Key, T1, Comp1> &map, const T& value = T()) 
       : _map(map.begin(), map.end()), _value(value) {}
     
-    /// \brief Constructs a map from an other StdMap.
+    /// \brief Constructs a map from an other \ref StdMap.
     template<typename T1, typename Comp1>
     StdMap(const StdMap<Key, T1, Comp1> &c) 
       : _map(c._map.begin(), c._map.end()), _value(c._value) {}
@@ -242,30 +254,58 @@
     };
   };
 
-  /// \brief Map for storing values for the range \c [0..size-1] range keys
+  ///Returns a \c StdMap class
+
+  ///This function just returns a \c StdMap class with specified 
+  ///default value.
+  ///\relates StdMap
+  template<typename K, typename V, typename Compare> 
+  inline StdMap<K, V, Compare> stdMap(const V& value = V()) {
+    return StdMap<K, V, Compare>(value);
+  }
+  
+  template<typename K, typename V> 
+  inline StdMap<K, V, std::less<K> > stdMap(const V& value = V()) {
+    return StdMap<K, V, std::less<K> >(value);
+  }
+  
+  ///Returns a \c StdMap class created from an appropriate \c std::map
+
+  ///This function just returns a \c StdMap class created from an 
+  ///appropriate \c std::map.
+  ///\relates StdMap
+  template<typename K, typename V, typename Compare> 
+  inline StdMap<K, V, Compare> stdMap( const std::map<K, V, Compare> &map, 
+                                       const V& value = V() ) {
+    return StdMap<K, V, Compare>(map, value);
+  }
+
+  /// \brief Map for storing values for keys from the range <tt>[0..size-1]</tt>
   ///
-  /// The current map has the \c [0..size-1] keyset and the values
+  /// This map has the <tt>[0..size-1]</tt> keyset and the values
   /// are stored in a \c std::vector<T>  container. It can be used with
   /// some data structures, for example \c UnionFind, \c BinHeap, when 
   /// the used items are small integer numbers.
   template <typename T>
-  class IntegerMap {
+  class IntegerMap : public MapBase<int, T> {
 
     template <typename T1>
     friend class IntegerMap;
 
   public:
 
-    typedef True ReferenceMapTag;
+    typedef MapBase<int, T> Parent;
     ///\e
-    typedef int Key;
+    typedef typename Parent::Key Key;
     ///\e
-    typedef T Value;
+    typedef typename Parent::Value Value;
     ///\e
     typedef T& Reference;
     ///\e
     typedef const T& ConstReference;
 
+    typedef True ReferenceMapTag;
+
   private:
     
     typedef std::vector<T> Vector;
@@ -276,12 +316,12 @@
     /// Constructor with specified default value
     IntegerMap(int size = 0, const T& value = T()) : _vector(size, value) {}
 
-    /// \brief Constructs the map from an appropriate std::vector.
+    /// \brief Constructs the map from an appropriate \c std::vector.
     template <typename T1>
     IntegerMap(const std::vector<T1>& vector) 
       : _vector(vector.begin(), vector.end()) {}
     
-    /// \brief Constructs a map from an other IntegerMap.
+    /// \brief Constructs a map from an other \ref IntegerMap.
     template <typename T1>
     IntegerMap(const IntegerMap<T1> &c) 
       : _vector(c._vector.begin(), c._vector.end()) {}
@@ -314,14 +354,23 @@
 
   };
 
+  ///Returns an \c IntegerMap class
+
+  ///This function just returns an \c IntegerMap class.
+  ///\relates IntegerMap
+  template<typename T>
+  inline IntegerMap<T> integerMap(int size = 0, const T& value = T()) {
+    return IntegerMap<T>(size, value);
+  }
+
   /// @}
 
   /// \addtogroup map_adaptors
   /// @{
 
-  /// \brief Identity mapping.
+  /// \brief Identity map.
   ///
-  /// This mapping gives back the given key as value without any
+  /// This map gives back the given key as value without any
   /// modification. 
   template <typename T>
   class IdentityMap : public MapBase<T, T> {
@@ -346,10 +395,11 @@
   }
   
 
-  ///Convert the \c Value of a map to another type.
-
-  ///This \c concepts::ReadMap "read only map"
-  ///converts the \c Value of a maps to type \c T.
+  ///\brief Convert the \c Value of a map to another type using
+  ///the default conversion.
+  ///
+  ///This \ref concepts::ReadMap "read only map"
+  ///converts the \c Value of a map to type \c T.
   ///Its \c Key is inherited from \c M.
   template <typename M, typename T> 
   class ConvertMap : public MapBase<typename M::Key, T> {
@@ -365,29 +415,29 @@
     ///\param _m is the underlying map
     ConvertMap(const M &_m) : m(_m) {};
 
-    /// \brief The subscript operator.
-    ///
-    /// The subscript operator.
-    /// \param k The key
-    /// \return The target of the edge 
+    ///\e
     Value operator[](const Key& k) const {return m[k];}
   };
   
-  ///Returns an \c ConvertMap class
+  ///Returns a \c ConvertMap class
 
-  ///This function just returns an \c ConvertMap class.
+  ///This function just returns a \c ConvertMap class.
   ///\relates ConvertMap
   template<typename T, typename M>
   inline ConvertMap<M, T> convertMap(const M &m) {
     return ConvertMap<M, T>(m);
   }
 
-  ///Simple wrapping of the map
+  ///Simple wrapping of a map
 
-  ///This \c concepts::ReadMap "read only map" returns the simple
+  ///This \ref concepts::ReadMap "read only map" returns the simple
   ///wrapping of the given map. Sometimes the reference maps cannot be
   ///combined with simple read maps. This map adaptor wraps the given
   ///map to simple read map.
+  ///
+  ///\sa SimpleWriteMap
+  ///
+  /// \todo Revise the misleading name 
   template<typename M> 
   class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
     const M& m;
@@ -403,12 +453,25 @@
     Value operator[](Key k) const {return m[k];}
   };
 
-  ///Simple writeable wrapping of the map
+  ///Returns a \c SimpleMap class
 
-  ///This \c concepts::ReadMap "read only map" returns the simple
+  ///This function just returns a \c SimpleMap class.
+  ///\relates SimpleMap
+  template<typename M>
+  inline SimpleMap<M> simpleMap(const M &m) {
+    return SimpleMap<M>(m);
+  }
+
+  ///Simple writable wrapping of a map
+
+  ///This \ref concepts::ReadWriteMap "read-write map" returns the simple
   ///wrapping of the given map. Sometimes the reference maps cannot be
   ///combined with simple read-write maps. This map adaptor wraps the
   ///given map to simple read-write map.
+  ///
+  ///\sa SimpleMap
+  ///
+  /// \todo Revise the misleading name
   template<typename M> 
   class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
     M& m;
@@ -426,12 +489,21 @@
     void set(Key k, const Value& c) { m.set(k, c); }
   };
 
+  ///Returns a \c SimpleWriteMap class
+
+  ///This function just returns a \c SimpleWriteMap class.
+  ///\relates SimpleWriteMap
+  template<typename M>
+  inline SimpleWriteMap<M> simpleWriteMap(M &m) {
+    return SimpleWriteMap<M>(m);
+  }
+
   ///Sum of two maps
 
-  ///This \c concepts::ReadMap "read only map" returns the sum of the two
-  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
-  ///The \c Key and \c Value of M2 must be convertible to those of \c M1.
-
+  ///This \ref concepts::ReadMap "read only map" returns the sum of the two
+  ///given maps.
+  ///Its \c Key and \c Value are inherited from \c M1.
+  ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
   template<typename M1, typename M2> 
   class AddMap : public MapBase<typename M1::Key, typename M1::Value> {
     const M1& m1;
@@ -461,7 +533,7 @@
 
   ///Shift a map with a constant.
 
-  ///This \c concepts::ReadMap "read only map" returns the sum of the
+  ///This \ref concepts::ReadMap "read only map" returns the sum of the
   ///given map and a constant value.
   ///Its \c Key and \c Value is inherited from \c M.
   ///
@@ -469,11 +541,13 @@
   ///\code
   ///  ShiftMap<X> sh(x,v);
   ///\endcode
-  ///is equivalent with
+  ///is equivalent to
   ///\code
   ///  ConstMap<X::Key, X::Value> c_tmp(v);
   ///  AddMap<X, ConstMap<X::Key, X::Value> > sh(x,v);
   ///\endcode
+  ///
+  ///\sa ShiftWriteMap
   template<typename M, typename C = typename M::Value> 
   class ShiftMap : public MapBase<typename M::Key, typename M::Value> {
     const M& m;
@@ -493,21 +567,13 @@
     Value operator[](Key k) const {return m[k] + v;}
   };
 
-  ///Shift a map with a constant.
+  ///Shift a map with a constant (ReadWrite version).
 
-  ///This \c concepts::ReadWriteMap "read-write map" returns the sum of the
+  ///This \ref concepts::ReadWriteMap "read-write map" returns the sum of the
   ///given map and a constant value. It makes also possible to write the map.
-  ///Its \c Key and \c Value is inherited from \c M.
+  ///Its \c Key and \c Value are inherited from \c M.
   ///
-  ///Actually,
-  ///\code
-  ///  ShiftMap<X> sh(x,v);
-  ///\endcode
-  ///is equivalent with
-  ///\code
-  ///  ConstMap<X::Key, X::Value> c_tmp(v);
-  ///  AddMap<X, ConstMap<X::Key, X::Value> > sh(x,v);
-  ///\endcode
+  ///\sa ShiftMap
   template<typename M, typename C = typename M::Value> 
   class ShiftWriteMap : public MapBase<typename M::Key, typename M::Value> {
     M& m;
@@ -529,7 +595,7 @@
     void set(Key k, const Value& c) { m.set(k, c - v); }
   };
   
-  ///Returns an \c ShiftMap class
+  ///Returns a \c ShiftMap class
 
   ///This function just returns an \c ShiftMap class.
   ///\relates ShiftMap
@@ -538,6 +604,10 @@
     return ShiftMap<M, C>(m,v);
   }
 
+  ///Returns a \c ShiftWriteMap class
+
+  ///This function just returns a \c ShiftWriteMap class.
+  ///\relates ShiftWriteMap
   template<typename M, typename C> 
   inline ShiftWriteMap<M, C> shiftMap(M &m,const C &v) {
     return ShiftWriteMap<M, C>(m,v);
@@ -545,9 +615,9 @@
 
   ///Difference of two maps
 
-  ///This \c concepts::ReadMap "read only map" returns the difference
-  ///of the values of the two
-  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
+  ///This \ref concepts::ReadMap "read only map" returns the difference
+  ///of the values of the two given maps.
+  ///Its \c Key and \c Value are inherited from \c M1.
   ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
 
   template<typename M1, typename M2> 
@@ -577,12 +647,10 @@
 
   ///Product of two maps
 
-  ///This \c concepts::ReadMap "read only map" returns the product of the
-  ///values of the two
-  ///given
-  ///maps. Its \c Key and \c Value will be inherited from \c M1.
+  ///This \ref concepts::ReadMap "read only map" returns the product of the
+  ///values of the two given maps.
+  ///Its \c Key and \c Value are inherited from \c M1.
   ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
-
   template<typename M1, typename M2> 
   class MulMap : public MapBase<typename M1::Key, typename M1::Value> {
     const M1& m1;
@@ -607,21 +675,23 @@
     return MulMap<M1, M2>(m1,m2);
   }
  
-  ///Scales a maps with a constant.
+  ///Scales a map with a constant.
 
-  ///This \c concepts::ReadMap "read only map" returns the value of the
+  ///This \ref concepts::ReadMap "read only map" returns the value of the
   ///given map multiplied from the left side with a constant value.
-  ///Its \c Key and \c Value is inherited from \c M.
+  ///Its \c Key and \c Value are inherited from \c M.
   ///
   ///Actually,
   ///\code
   ///  ScaleMap<X> sc(x,v);
   ///\endcode
-  ///is equivalent with
+  ///is equivalent to
   ///\code
   ///  ConstMap<X::Key, X::Value> c_tmp(v);
   ///  MulMap<X, ConstMap<X::Key, X::Value> > sc(x,v);
   ///\endcode
+  ///
+  ///\sa ScaleWriteMap
   template<typename M, typename C = typename M::Value> 
   class ScaleMap : public MapBase<typename M::Key, typename M::Value> {
     const M& m;
@@ -641,12 +711,15 @@
     Value operator[](Key k) const {return v * m[k];}
   };
 
-  ///Scales a maps with a constant.
+  ///Scales a map with a constant (ReadWrite version).
 
-  ///This \c concepts::ReadWriteMap "read-write map" returns the value of the
+  ///This \ref concepts::ReadWriteMap "read-write map" returns the value of the
   ///given map multiplied from the left side with a constant value. It can
-  ///be used as write map also if the given multiplier is not zero.
-  ///Its \c Key and \c Value is inherited from \c M.
+  ///also be used as write map if the \c / operator is defined between
+  ///\c Value and \c C and the given multiplier is not zero.
+  ///Its \c Key and \c Value are inherited from \c M.
+  ///
+  ///\sa ScaleMap
   template<typename M, typename C = typename M::Value> 
   class ScaleWriteMap : public MapBase<typename M::Key, typename M::Value> {
     M& m;
@@ -668,15 +741,19 @@
     void set(Key k, const Value& c) { m.set(k, c / v);}
   };
   
-  ///Returns an \c ScaleMap class
+  ///Returns a \c ScaleMap class
 
-  ///This function just returns an \c ScaleMap class.
+  ///This function just returns a \c ScaleMap class.
   ///\relates ScaleMap
   template<typename M, typename C> 
   inline ScaleMap<M, C> scaleMap(const M &m,const C &v) {
     return ScaleMap<M, C>(m,v);
   }
 
+  ///Returns a \c ScaleWriteMap class
+
+  ///This function just returns a \c ScaleWriteMap class.
+  ///\relates ScaleWriteMap
   template<typename M, typename C> 
   inline ScaleWriteMap<M, C> scaleMap(M &m,const C &v) {
     return ScaleWriteMap<M, C>(m,v);
@@ -684,11 +761,10 @@
 
   ///Quotient of two maps
 
-  ///This \c concepts::ReadMap "read only map" returns the quotient of the
-  ///values of the two
-  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
+  ///This \ref concepts::ReadMap "read only map" returns the quotient of the
+  ///values of the two given maps.
+  ///Its \c Key and \c Value are inherited from \c M1.
   ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
-
   template<typename M1, typename M2> 
   class DivMap : public MapBase<typename M1::Key, typename M1::Value> {
     const M1& m1;
@@ -715,19 +791,20 @@
   
   ///Composition of two maps
 
-  ///This \c concepts::ReadMap "read only map" returns the composition of
-  ///two
-  ///given maps. That is to say, if \c m1 is of type \c M1 and \c m2 is
-  ///of \c M2,
+  ///This \ref concepts::ReadMap "read only map" returns the composition of
+  ///two given maps.
+  ///That is to say, if \c m1 is of type \c M1 and \c m2 is of \c M2,
   ///then for
   ///\code
   ///  ComposeMap<M1, M2> cm(m1,m2);
   ///\endcode
-  /// <tt>cm[x]</tt> will be equal to <tt>m1[m2[x]]</tt>
+  /// <tt>cm[x]</tt> will be equal to <tt>m1[m2[x]]</tt>.
   ///
-  ///Its \c Key is inherited from \c M2 and its \c Value is from
-  ///\c M1.
-  ///The \c M2::Value must be convertible to \c M1::Key.
+  ///Its \c Key is inherited from \c M2 and its \c Value is from \c M1.
+  ///\c M2::Value must be convertible to \c M1::Key.
+  ///
+  ///\sa CombineMap
+  ///
   ///\todo Check the requirements.
   template <typename M1, typename M2> 
   class ComposeMap : public MapBase<typename M2::Key, typename M1::Value> {
@@ -755,27 +832,27 @@
     return ComposeMap<M1, M2>(m1,m2);
   }
   
-  ///Combines of two maps using an STL (binary) functor.
+  ///Combine of two maps using an STL (binary) functor.
 
-  ///Combines of two maps using an STL (binary) functor.
+  ///Combine of two maps using an STL (binary) functor.
   ///
-  ///
-  ///This \c concepts::ReadMap "read only map" takes two maps and a
-  ///binary functor and returns the composition of
-  ///the two
+  ///This \ref concepts::ReadMap "read only map" takes two maps and a
+  ///binary functor and returns the composition of the two
   ///given maps unsing the functor. 
   ///That is to say, if \c m1 and \c m2 is of type \c M1 and \c M2
-  ///and \c f is of \c F,
-  ///then for
+  ///and \c f is of \c F, then for
   ///\code
   ///  CombineMap<M1, M2,F,V> cm(m1,m2,f);
   ///\endcode
   /// <tt>cm[x]</tt> will be equal to <tt>f(m1[x],m2[x])</tt>
   ///
   ///Its \c Key is inherited from \c M1 and its \c Value is \c V.
-  ///The \c M2::Value and \c M1::Value must be convertible to the corresponding
+  ///\c M2::Value and \c M1::Value must be convertible to the corresponding
   ///input parameter of \c F and the return type of \c F must be convertible
   ///to \c V.
+  ///
+  ///\sa ComposeMap
+  ///
   ///\todo Check the requirements.
   template<typename M1, typename M2, typename F,
 	   typename V = typename F::result_type> 
@@ -801,15 +878,15 @@
   ///
   ///For example if \c m1 and \c m2 are both \c double valued maps, then 
   ///\code
-  ///combineMap<double>(m1,m2,std::plus<double>())
+  ///combineMap(m1,m2,std::plus<double>())
   ///\endcode
-  ///is equivalent with
+  ///is equivalent to
   ///\code
   ///addMap(m1,m2)
   ///\endcode
   ///
   ///This function is specialized for adaptable binary function
-  ///classes and c++ functions.
+  ///classes and C++ functions.
   ///
   ///\relates CombineMap
   template<typename M1, typename M2, typename F, typename V> 
@@ -832,12 +909,12 @@
 
   ///Negative value of a map
 
-  ///This \c concepts::ReadMap "read only map" returns the negative
-  ///value of the
-  ///value returned by the
-  ///given map. Its \c Key and \c Value will be inherited from \c M.
+  ///This \ref concepts::ReadMap "read only map" returns the negative
+  ///value of the value returned by the given map.
+  ///Its \c Key and \c Value are inherited from \c M.
   ///The unary \c - operator must be defined for \c Value, of course.
-
+  ///
+  ///\sa NegWriteMap
   template<typename M> 
   class NegMap : public MapBase<typename M::Key, typename M::Value> {
     const M& m;
@@ -852,13 +929,14 @@
     Value operator[](Key k) const {return -m[k];}
   };
   
-  ///Negative value of a map
+  ///Negative value of a map (ReadWrite version)
 
-  ///This \c concepts::ReadWriteMap "read-write map" returns the negative
-  ///value of the value returned by the
-  ///given map. Its \c Key and \c Value will be inherited from \c M.
+  ///This \ref concepts::ReadWriteMap "read-write map" returns the negative
+  ///value of the value returned by the given map.
+  ///Its \c Key and \c Value are inherited from \c M.
   ///The unary \c - operator must be defined for \c Value, of course.
-
+  ///
+  /// \sa NegMap
   template<typename M> 
   class NegWriteMap : public MapBase<typename M::Key, typename M::Value> {
     M& m;
@@ -884,6 +962,10 @@
     return NegMap<M>(m);
   }
 
+  ///Returns a \c NegWriteMap class
+
+  ///This function just returns a \c NegWriteMap class.
+  ///\relates NegWriteMap
   template <typename M> 
   inline NegWriteMap<M> negMap(M &m) {
     return NegWriteMap<M>(m);
@@ -891,12 +973,10 @@
 
   ///Absolute value of a map
 
-  ///This \c concepts::ReadMap "read only map" returns the absolute value
-  ///of the
-  ///value returned by the
-  ///given map. Its \c Key and \c Value will be inherited
-  ///from <tt>M</tt>. <tt>Value</tt>
-  ///must be comparable to <tt>0</tt> and the unary <tt>-</tt>
+  ///This \ref concepts::ReadMap "read only map" returns the absolute value
+  ///of the value returned by the given map.
+  ///Its \c Key and \c Value are inherited from \c M. 
+  ///\c Value must be comparable to \c 0 and the unary \c -
   ///operator must be defined for it, of course.
   ///
   ///\bug We need a unified way to handle the situation below:
@@ -930,9 +1010,9 @@
 
   };
   
-  ///Returns a \c AbsMap class
+  ///Returns an \c AbsMap class
 
-  ///This function just returns a \c AbsMap class.
+  ///This function just returns an \c AbsMap class.
   ///\relates AbsMap
   template<typename M> 
   inline AbsMap<M> absMap(const M &m) {
@@ -941,15 +1021,18 @@
 
   ///Converts an STL style functor to a map
 
-  ///This \c concepts::ReadMap "read only map" returns the value
-  ///of a
-  ///given map.
+  ///This \ref concepts::ReadMap "read only map" returns the value
+  ///of a given functor.
   ///
   ///Template parameters \c K and \c V will become its
-  ///\c Key and \c Value. They must be given explicitely
-  ///because a functor does not provide such typedefs.
+  ///\c Key and \c Value. 
+  ///In most cases they have to be given explicitly because a 
+  ///functor typically does not provide \c argument_type and 
+  ///\c result_type typedefs.
   ///
   ///Parameter \c F is the type of the used functor.
+  ///
+  ///\sa MapFunctor
   template<typename F, 
 	   typename K = typename F::argument_type, 
 	   typename V = typename F::result_type> 
@@ -970,8 +1053,9 @@
 
   ///This function just returns a \c FunctorMap class.
   ///
-  ///It is specialized for adaptable function classes and
-  ///c++ functions.
+  ///This function is specialized for adaptable binary function
+  ///classes and C++ functions.
+  ///
   ///\relates FunctorMap
   template<typename K, typename V, typename F> inline 
   FunctorMap<F, K, V> functorMap(const F &f) {
@@ -994,11 +1078,13 @@
   ///Converts a map to an STL style (unary) functor
 
   ///This class Converts a map to an STL style (unary) functor.
-  ///that is it provides an <tt>operator()</tt> to read its values.
+  ///That is it provides an <tt>operator()</tt> to read its values.
   ///
   ///For the sake of convenience it also works as
-  ///a ususal \c concepts::ReadMap "readable map",
+  ///a ususal \ref concepts::ReadMap "readable map",
   ///i.e. <tt>operator[]</tt> and the \c Key and \c Value typedefs also exist.
+  ///
+  ///\sa FunctorMap
   template <typename M> 
   class MapFunctor : public MapBase<typename M::Key, typename M::Value> {
     const M& m;
@@ -1027,14 +1113,17 @@
     return MapFunctor<M>(m);
   }
 
-  ///Applies all map setting operations to two maps
+  ///Just readable version of \ref ForkWriteMap
 
-  ///This map has two \c concepts::ReadMap "readable map"
+  ///This map has two \ref concepts::ReadMap "readable map"
   ///parameters and each read request will be passed just to the
-  ///first map. This class is the just readable map type of the ForkWriteMap.
+  ///first map. This class is the just readable map type of \c ForkWriteMap.
   ///
-  ///The \c Key and \c Value will be inherited from \c M1.
-  ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
+  ///The \c Key and \c Value are inherited from \c M1.
+  ///The \c Key and \c Value of \c M2 must be convertible from those of \c M1.
+  ///
+  ///\sa ForkWriteMap
+
   template<typename  M1, typename M2> 
   class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
     const M1& m1;
@@ -1053,14 +1142,16 @@
 
   ///Applies all map setting operations to two maps
 
-  ///This map has two \c concepts::WriteMap "writable map"
+  ///This map has two \ref concepts::WriteMap "writable map"
   ///parameters and each write request will be passed to both of them.
-  ///If \c M1 is also \c concepts::ReadMap "readable",
+  ///If \c M1 is also \ref concepts::ReadMap "readable",
   ///then the read operations will return the
   ///corresponding values of \c M1.
   ///
-  ///The \c Key and \c Value will be inherited from \c M1.
-  ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
+  ///The \c Key and \c Value are inherited from \c M1.
+  ///The \c Key and \c Value of \c M2 must be convertible from those of \c M1.
+  ///
+  ///\sa ForkMap
   template<typename  M1, typename M2> 
   class ForkWriteMap : public MapBase<typename M1::Key, typename M1::Value> {
     M1& m1;
@@ -1078,16 +1169,19 @@
     void set(Key k, const Value &v) {m1.set(k,v); m2.set(k,v);}
   };
   
-  ///Returns an \c ForkMap class
+  ///Returns a \c ForkMap class
 
-  ///This function just returns an \c ForkMap class.
-  ///
+  ///This function just returns a \c ForkMap class.
   ///\relates ForkMap
   template <typename M1, typename M2> 
   inline ForkMap<M1, M2> forkMap(const M1 &m1, const M2 &m2) {
     return ForkMap<M1, M2>(m1,m2);
   }
 
+  ///Returns a \c ForkWriteMap class
+
+  ///This function just returns a \c ForkWriteMap class.
+  ///\relates ForkWriteMap
   template <typename M1, typename M2> 
   inline ForkWriteMap<M1, M2> forkMap(M1 &m1, M2 &m2) {
     return ForkWriteMap<M1, M2>(m1,m2);
@@ -1099,11 +1193,11 @@
   
   ///Logical 'not' of a map
   
-  ///This bool \c concepts::ReadMap "read only map" returns the 
-  ///logical negation of
-  ///value returned by the
-  ///given map. Its \c Key and will be inherited from \c M,
-  ///its Value is <tt>bool</tt>.
+  ///This bool \ref concepts::ReadMap "read only map" returns the 
+  ///logical negation of the value returned by the given map.
+  ///Its \c Key is inherited from \c M, its \c Value is \c bool.
+  ///
+  ///\sa NotWriteMap
   template <typename M> 
   class NotMap : public MapBase<typename M::Key, bool> {
     const M& m;
@@ -1118,13 +1212,14 @@
     Value operator[](Key k) const {return !m[k];}
   };
 
-  ///Logical 'not' of a map with writing possibility
+  ///Logical 'not' of a map (ReadWrie version)
   
-  ///This bool \c concepts::ReadWriteMap "read-write map" returns the 
-  ///logical negation of value returned by the given map. When it is set,
+  ///This bool \ref concepts::ReadWriteMap "read-write map" returns the 
+  ///logical negation of the value returned by the given map. When it is set,
   ///the opposite value is set to the original map.
-  ///Its \c Key and will be inherited from \c M,
-  ///its Value is <tt>bool</tt>.
+  ///Its \c Key is inherited from \c M, its \c Value is \c bool.
+  ///
+  ///\sa NotMap
   template <typename M> 
   class NotWriteMap : public MapBase<typename M::Key, bool> {
     M& m;
@@ -1150,6 +1245,10 @@
     return NotMap<M>(m);
   }
   
+  ///Returns a \c NotWriteMap class
+  
+  ///This function just returns a \c NotWriteMap class.
+  ///\relates NotWriteMap
   template <typename M> 
   inline NotWriteMap<M> notMap(M &m) {
     return NotWriteMap<M>(m);
@@ -1181,16 +1280,17 @@
   }
   
 
-  /// \brief Writable bool map for store each true assigned elements.
+  /// \brief Writable bool map for logging each \c true assigned element
   ///
-  /// Writable bool map to store each true assigned elements. It will
-  /// copies all the keys set to true to the given iterator.
+  /// A \ref concepts::ReadWriteMap "read-write" bool map for logging 
+  /// each \c true assigned element, i.e it copies all the keys set 
+  /// to \c true to the given iterator.
   ///
   /// \note The container of the iterator should contain space 
   /// for each element.
   ///
-  /// The next example shows how can you write the nodes directly
-  /// to the standard output.
+  /// The following example shows how you can write the edges found by 
+  /// the \ref Prim algorithm directly to the standard output.
   ///\code
   /// typedef IdMap<UGraph, UEdge> UEdgeIdMap;
   /// UEdgeIdMap uedgeId(ugraph);
@@ -1203,6 +1303,10 @@
   ///
   /// prim(ugraph, cost, writerMap);
   ///\endcode
+  ///
+  ///\sa BackInserterBoolMap 
+  ///\sa FrontInserterBoolMap 
+  ///\sa InserterBoolMap 
   template <typename _Iterator, 
             typename _Functor =
             _maps_bits::Identity<typename _maps_bits::
@@ -1220,17 +1324,17 @@
     StoreBoolMap(Iterator it, const Functor& functor = Functor()) 
       : _begin(it), _end(it), _functor(functor) {}
 
-    /// Gives back the given iterator set for the first time.
+    /// Gives back the given iterator set for the first key
     Iterator begin() const {
       return _begin;
     }
  
-    /// Gives back the iterator after the last set operation.
+    /// Gives back the the 'after the last' iterator
     Iterator end() const {
       return _end;
     }
 
-    /// Setter function of the map
+    /// The \c set function of the map
     void set(const Key& key, Value value) const {
       if (value) {
 	*_end++ = _functor(key);
@@ -1243,26 +1347,30 @@
     Functor _functor;
   };
 
-  /// \brief Writable bool map for store each true assigned elements in 
+  /// \brief Writable bool map for logging each \c true assigned element in 
   /// a back insertable container.
   ///
-  /// Writable bool map for store each true assigned elements in a back 
-  /// insertable container. It will push back all the keys set to true into
-  /// the container. It can be used to retrieve the items into a standard
-  /// container. The next example shows how can you store the undirected
-  /// edges in a vector with prim algorithm.
+  /// Writable bool map for logging each \c true assigned element by pushing
+  /// them into a back insertable container.
+  /// It can be used to retrieve the items into a standard
+  /// container. The next example shows how you can store the
+  /// edges found by the Prim algorithm in a vector.
   ///
   ///\code
   /// vector<UEdge> span_tree_uedges;
   /// BackInserterBoolMap<vector<UEdge> > inserter_map(span_tree_uedges);
   /// prim(ugraph, cost, inserter_map);
   ///\endcode
+  ///
+  ///\sa StoreBoolMap
+  ///\sa FrontInserterBoolMap
+  ///\sa InserterBoolMap
   template <typename Container,
             typename Functor =
             _maps_bits::Identity<typename Container::value_type> >
   class BackInserterBoolMap {
   public:
-    typedef typename Container::value_type Key;
+    typedef typename Functor::argument_type Key;
     typedef bool Value;
 
     /// Constructor
@@ -1270,7 +1378,7 @@
                         const Functor& _functor = Functor()) 
       : container(_container), functor(_functor) {}
 
-    /// Setter function of the map
+    /// The \c set function of the map
     void set(const Key& key, Value value) {
       if (value) {
 	container.push_back(functor(key));
@@ -1282,18 +1390,22 @@
     Functor functor;
   };
 
-  /// \brief Writable bool map for store each true assigned elements in 
+  /// \brief Writable bool map for logging each \c true assigned element in 
   /// a front insertable container.
   ///
-  /// Writable bool map for store each true assigned elements in a front 
-  /// insertable container. It will push front all the keys set to \c true into
-  /// the container. For example see the BackInserterBoolMap.
+  /// Writable bool map for logging each \c true assigned element by pushing
+  /// them into a front insertable container.
+  /// It can be used to retrieve the items into a standard
+  /// container. For example see \ref BackInserterBoolMap.
+  ///
+  ///\sa BackInserterBoolMap
+  ///\sa InserterBoolMap
   template <typename Container,
             typename Functor =
             _maps_bits::Identity<typename Container::value_type> >
   class FrontInserterBoolMap {
   public:
-    typedef typename Container::value_type Key;
+    typedef typename Functor::argument_type Key;
     typedef bool Value;
 
     /// Constructor
@@ -1301,10 +1413,10 @@
                          const Functor& _functor = Functor()) 
       : container(_container), functor(_functor) {}
 
-    /// Setter function of the map
+    /// The \c set function of the map
     void set(const Key& key, Value value) {
       if (value) {
-	container.push_front(key);
+	container.push_front(functor(key));
       }
     }
     
@@ -1313,12 +1425,14 @@
     Functor functor;
   };
 
-  /// \brief Writable bool map for store each true assigned elements in 
+  /// \brief Writable bool map for storing each \c true assigned element in 
   /// an insertable container.
   ///
-  /// Writable bool map for store each true assigned elements in an 
+  /// Writable bool map for storing each \c true assigned element in an 
   /// insertable container. It will insert all the keys set to \c true into
-  /// the container. If you want to store the cut edges of the strongly
+  /// the container.
+  ///
+  /// For example, if you want to store the cut arcs of the strongly
   /// connected components in a set you can use the next code:
   ///
   ///\code
@@ -1326,6 +1440,9 @@
   /// InserterBoolMap<set<Edge> > inserter_map(cut_edges);
   /// stronglyConnectedCutEdges(graph, cost, inserter_map);
   ///\endcode
+  ///
+  ///\sa BackInserterBoolMap
+  ///\sa FrontInserterBoolMap
   template <typename Container,
             typename Functor =
             _maps_bits::Identity<typename Container::value_type> >
@@ -1334,19 +1451,29 @@
     typedef typename Container::value_type Key;
     typedef bool Value;
 
-    /// Constructor
+    /// Constructor with specified iterator
+    
+    /// Constructor with specified iterator.
+    /// \param _container The container for storing the elements.
+    /// \param _it The elements will be inserted before this iterator.
+    /// \param _functor The functor that is used when an element is stored.
     InserterBoolMap(Container& _container, typename Container::iterator _it,
                     const Functor& _functor = Functor()) 
       : container(_container), it(_it), functor(_functor) {}
 
     /// Constructor
+
+    /// Constructor without specified iterator.
+    /// The elements will be inserted before <tt>_container.end()</tt>.
+    /// \param _container The container for storing the elements.
+    /// \param _functor The functor that is used when an element is stored.
     InserterBoolMap(Container& _container, const Functor& _functor = Functor())
       : container(_container), it(_container.end()), functor(_functor) {}
 
-    /// Setter function of the map
+    /// The \c set function of the map
     void set(const Key& key, Value value) {
       if (value) {
-	it = container.insert(it, key);
+	it = container.insert(it, functor(key));
         ++it;
       }
     }
@@ -1357,13 +1484,13 @@
     Functor functor;
   };
 
-  /// \brief Fill the true set elements with a given value.
+  /// \brief Writable bool map for filling each \c true assigned element with a 
+  /// given value.
   ///
-  /// Writable bool map to fill the elements set to \c true with a given value.
-  /// The value can set 
-  /// the container.
+  /// Writable bool map for filling each \c true assigned element with a 
+  /// given value. The value can set the container.
   ///
-  /// The next code finds the connected components of the undirected graph
+  /// The following code finds the connected components of a graph
   /// and stores it in the \c comp map:
   ///\code
   /// typedef UGraph::NodeMap<int> ComponentMap;
@@ -1411,7 +1538,7 @@
       fill = _fill;
     } 
 
-    /// Setter function of the map
+    /// The \c set function of the map
     void set(const Key& key, Value value) {
       if (value) {
 	map.set(key, fill);
@@ -1424,11 +1551,12 @@
   };
 
 
-  /// \brief Writable bool map which stores for each true assigned elements  
-  /// the setting order number.
+  /// \brief Writable bool map for storing the sequence number of 
+  /// \c true assignments.  
   ///
-  /// Writable bool map which stores for each true assigned elements  
-  /// the setting order number. It make easy to calculate the leaving
+  /// Writable bool map that stores for each \c true assigned elements  
+  /// the sequence number of this setting.
+  /// It makes it easy to calculate the leaving
   /// order of the nodes in the \c Dfs algorithm.
   ///
   ///\code
@@ -1447,9 +1575,9 @@
   /// }
   ///\endcode
   ///
-  /// The discovering order can be stored a little harder because the
+  /// The storing of the discovering order is more difficult because the
   /// ReachedMap should be readable in the dfs algorithm but the setting
-  /// order map is not readable. Now we should use the fork map:
+  /// order map is not readable. Thus we must use the fork map:
   ///
   ///\code
   /// typedef Graph::NodeMap<int> OrderMap;
@@ -1487,7 +1615,7 @@
       return counter;
     }
 
-    /// Setter function of the map
+    /// The \c set function of the map
     void set(const Key& key, Value value) {
       if (value) {
 	map.set(key, counter++);