Several doc improvements and fixes in maps.h.
authorPeter Kovacs <kpeter@inf.elte.hu>
Fri, 04 Jan 2008 08:08:50 +0100
changeset 290cb4ba427bfd
parent 26 61bf7f22a6d6
child 30 72364ba3466d
Several doc improvements and fixes in maps.h.
lemon/maps.h
     1.1 --- a/lemon/maps.h	Sat Dec 22 14:04:22 2007 +0000
     1.2 +++ b/lemon/maps.h	Fri Jan 04 08:08:50 2008 +0100
     1.3 @@ -52,9 +52,10 @@
     1.4  
     1.5    /// Null map. (a.k.a. DoNothingMap)
     1.6  
     1.7 -  /// If you have to provide a map only for its type definitions,
     1.8 -  /// or if you have to provide a writable map, but
     1.9 -  /// data written to it will sent to <tt>/dev/null</tt>...
    1.10 +  /// This map can be used if you have to provide a map only for
    1.11 +  /// its type definitions, or if you have to provide a writable map, 
    1.12 +  /// but data written to it is not required (i.e. it will be sent to 
    1.13 +  /// <tt>/dev/null</tt>).
    1.14    template<typename K, typename T>
    1.15    class NullMap : public MapBase<K, T> {
    1.16    public:
    1.17 @@ -68,6 +69,10 @@
    1.18      void set(const K&, const T&) {}
    1.19    };
    1.20  
    1.21 +  ///Returns a \c NullMap class
    1.22 +
    1.23 +  ///This function just returns a \c NullMap class.
    1.24 +  ///\relates NullMap
    1.25    template <typename K, typename V> 
    1.26    NullMap<K, V> nullMap() {
    1.27      return NullMap<K, V>();
    1.28 @@ -90,13 +95,15 @@
    1.29  
    1.30      /// Default constructor
    1.31  
    1.32 +    /// Default constructor.
    1.33      /// The value of the map will be uninitialized. 
    1.34      /// (More exactly it will be default constructed.)
    1.35      ConstMap() {}
    1.36 -    ///\e
    1.37 +    
    1.38 +    /// Constructor with specified initial value
    1.39  
    1.40 -    /// \param _v The initial value of the map.
    1.41 -    ///
    1.42 +    /// Constructor with specified initial value.
    1.43 +    /// \param _v is the initial value of the map.
    1.44      ConstMap(const T &_v) : v(_v) {}
    1.45      
    1.46      ///\e
    1.47 @@ -158,8 +165,8 @@
    1.48  
    1.49    ///Map based on std::map
    1.50  
    1.51 -  ///This is essentially a wrapper for \c std::map. With addition that
    1.52 -  ///you can specify a default value different from \c Value() .
    1.53 +  ///This is essentially a wrapper for \c std::map with addition that
    1.54 +  ///you can specify a default value different from \c Value().
    1.55    template <typename K, typename T, typename Compare = std::less<K> >
    1.56    class StdMap {
    1.57      template <typename K1, typename T1, typename C1>
    1.58 @@ -321,9 +328,9 @@
    1.59    /// \addtogroup map_adaptors
    1.60    /// @{
    1.61  
    1.62 -  /// \brief Identity mapping.
    1.63 +  /// \brief Identity map.
    1.64    ///
    1.65 -  /// This mapping gives back the given key as value without any
    1.66 +  /// This map gives back the given key as value without any
    1.67    /// modification. 
    1.68    template <typename T>
    1.69    class IdentityMap : public MapBase<T, T> {
    1.70 @@ -352,7 +359,7 @@
    1.71    ///the default conversion.
    1.72    ///
    1.73    ///This \c concepts::ReadMap "read only map"
    1.74 -  ///converts the \c Value of a maps to type \c T.
    1.75 +  ///converts the \c Value of a map to type \c T.
    1.76    ///Its \c Key is inherited from \c M.
    1.77    template <typename M, typename T> 
    1.78    class ConvertMap : public MapBase<typename M::Key, T> {
    1.79 @@ -364,8 +371,8 @@
    1.80  
    1.81      ///Constructor
    1.82  
    1.83 -    ///Constructor
    1.84 -    ///\param _m is the underlying map
    1.85 +    ///Constructor.
    1.86 +    ///\param _m is the underlying map.
    1.87      ConvertMap(const M &_m) : m(_m) {};
    1.88  
    1.89      /// \brief The subscript operator.
    1.90 @@ -374,23 +381,25 @@
    1.91      Value operator[](const Key& k) const {return m[k];}
    1.92    };
    1.93    
    1.94 -  ///Returns an \c ConvertMap class
    1.95 +  ///Returns a \c ConvertMap class
    1.96  
    1.97 -  ///This function just returns an \c ConvertMap class.
    1.98 +  ///This function just returns a \c ConvertMap class.
    1.99    ///\relates ConvertMap
   1.100    template<typename T, typename M>
   1.101    inline ConvertMap<M, T> convertMap(const M &m) {
   1.102      return ConvertMap<M, T>(m);
   1.103    }
   1.104  
   1.105 -  ///Simple wrapping of the map
   1.106 +  ///Simple wrapping of a map
   1.107  
   1.108    ///This \c concepts::ReadMap "read only map" returns the simple
   1.109    ///wrapping of the given map. Sometimes the reference maps cannot be
   1.110    ///combined with simple read maps. This map adaptor wraps the given
   1.111    ///map to simple read map.
   1.112    ///
   1.113 -  /// \todo Revise the misleading name
   1.114 +  ///\sa SimpleWriteMap
   1.115 +  ///
   1.116 +  /// \todo Revise the misleading name 
   1.117    template<typename M> 
   1.118    class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
   1.119      const M& m;
   1.120 @@ -406,13 +415,15 @@
   1.121      Value operator[](Key k) const {return m[k];}
   1.122    };
   1.123  
   1.124 -  ///Simple writeable wrapping of the map
   1.125 +  ///Simple writable wrapping of the map
   1.126  
   1.127    ///This \c concepts::WriteMap "write map" returns the simple
   1.128    ///wrapping of the given map. Sometimes the reference maps cannot be
   1.129    ///combined with simple read-write maps. This map adaptor wraps the
   1.130    ///given map to simple read-write map.
   1.131    ///
   1.132 +  ///\sa SimpleMap
   1.133 +  ///
   1.134    /// \todo Revise the misleading name
   1.135    template<typename M> 
   1.136    class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
   1.137 @@ -434,9 +445,9 @@
   1.138    ///Sum of two maps
   1.139  
   1.140    ///This \c concepts::ReadMap "read only map" returns the sum of the two
   1.141 -  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
   1.142 +  ///given maps.
   1.143 +  ///Its \c Key and \c Value are inherited from \c M1.
   1.144    ///The \c Key and \c Value of M2 must be convertible to those of \c M1.
   1.145 -
   1.146    template<typename M1, typename M2> 
   1.147    class AddMap : public MapBase<typename M1::Key, typename M1::Value> {
   1.148      const M1& m1;
   1.149 @@ -468,17 +479,19 @@
   1.150  
   1.151    ///This \c concepts::ReadMap "read only map" returns the sum of the
   1.152    ///given map and a constant value.
   1.153 -  ///Its \c Key and \c Value is inherited from \c M.
   1.154 +  ///Its \c Key and \c Value are inherited from \c M.
   1.155    ///
   1.156    ///Actually,
   1.157    ///\code
   1.158    ///  ShiftMap<X> sh(x,v);
   1.159    ///\endcode
   1.160 -  ///is equivalent with
   1.161 +  ///is equivalent to
   1.162    ///\code
   1.163    ///  ConstMap<X::Key, X::Value> c_tmp(v);
   1.164    ///  AddMap<X, ConstMap<X::Key, X::Value> > sh(x,v);
   1.165    ///\endcode
   1.166 +  ///
   1.167 +  ///\sa ShiftWriteMap
   1.168    template<typename M, typename C = typename M::Value> 
   1.169    class ShiftMap : public MapBase<typename M::Key, typename M::Value> {
   1.170      const M& m;
   1.171 @@ -490,29 +503,21 @@
   1.172  
   1.173      ///Constructor
   1.174  
   1.175 -    ///Constructor
   1.176 -    ///\param _m is the undelying map
   1.177 -    ///\param _v is the shift value
   1.178 +    ///Constructor.
   1.179 +    ///\param _m is the undelying map.
   1.180 +    ///\param _v is the shift value.
   1.181      ShiftMap(const M &_m, const C &_v ) : m(_m), v(_v) {};
   1.182      ///\e
   1.183      Value operator[](Key k) const {return m[k] + v;}
   1.184    };
   1.185  
   1.186 -  ///Shift a map with a constant. This map is also writable.
   1.187 +  ///Shift a map with a constant (ReadWrite version).
   1.188  
   1.189    ///This \c concepts::ReadWriteMap "read-write map" returns the sum of the
   1.190    ///given map and a constant value. It makes also possible to write the map.
   1.191 -  ///Its \c Key and \c Value is inherited from \c M.
   1.192 +  ///Its \c Key and \c Value are inherited from \c M.
   1.193    ///
   1.194 -  ///Actually,
   1.195 -  ///\code
   1.196 -  ///  ShiftMap<X> sh(x,v);
   1.197 -  ///\endcode
   1.198 -  ///is equivalent with
   1.199 -  ///\code
   1.200 -  ///  ConstMap<X::Key, X::Value> c_tmp(v);
   1.201 -  ///  AddMap<X, ConstMap<X::Key, X::Value> > sh(x,v);
   1.202 -  ///\endcode
   1.203 +  ///\sa ShiftMap
   1.204    template<typename M, typename C = typename M::Value> 
   1.205    class ShiftWriteMap : public MapBase<typename M::Key, typename M::Value> {
   1.206      M& m;
   1.207 @@ -524,9 +529,9 @@
   1.208  
   1.209      ///Constructor
   1.210  
   1.211 -    ///Constructor
   1.212 -    ///\param _m is the undelying map
   1.213 -    ///\param _v is the shift value
   1.214 +    ///Constructor.
   1.215 +    ///\param _m is the undelying map.
   1.216 +    ///\param _v is the shift value.
   1.217      ShiftWriteMap(M &_m, const C &_v ) : m(_m), v(_v) {};
   1.218      /// \e
   1.219      Value operator[](Key k) const {return m[k] + v;}
   1.220 @@ -534,15 +539,19 @@
   1.221      void set(Key k, const Value& c) { m.set(k, c - v); }
   1.222    };
   1.223    
   1.224 -  ///Returns an \c ShiftMap class
   1.225 +  ///Returns a \c ShiftMap class
   1.226  
   1.227 -  ///This function just returns an \c ShiftMap class.
   1.228 +  ///This function just returns a \c ShiftMap class.
   1.229    ///\relates ShiftMap
   1.230    template<typename M, typename C> 
   1.231    inline ShiftMap<M, C> shiftMap(const M &m,const C &v) {
   1.232      return ShiftMap<M, C>(m,v);
   1.233    }
   1.234  
   1.235 +  ///Returns a \c ShiftWriteMap class
   1.236 +
   1.237 +  ///This function just returns a \c ShiftWriteMap class.
   1.238 +  ///\relates ShiftWriteMap
   1.239    template<typename M, typename C> 
   1.240    inline ShiftWriteMap<M, C> shiftMap(M &m,const C &v) {
   1.241      return ShiftWriteMap<M, C>(m,v);
   1.242 @@ -551,8 +560,8 @@
   1.243    ///Difference of two maps
   1.244  
   1.245    ///This \c concepts::ReadMap "read only map" returns the difference
   1.246 -  ///of the values of the two
   1.247 -  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
   1.248 +  ///of the values of the two given maps.
   1.249 +  ///Its \c Key and \c Value are inherited from \c M1.
   1.250    ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
   1.251    ///
   1.252    /// \todo Revise the misleading name
   1.253 @@ -584,11 +593,9 @@
   1.254    ///Product of two maps
   1.255  
   1.256    ///This \c concepts::ReadMap "read only map" returns the product of the
   1.257 -  ///values of the two
   1.258 -  ///given
   1.259 -  ///maps. Its \c Key and \c Value will be inherited from \c M1.
   1.260 +  ///values of the two given maps.
   1.261 +  ///Its \c Key and \c Value are inherited from \c M1.
   1.262    ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
   1.263 -
   1.264    template<typename M1, typename M2> 
   1.265    class MulMap : public MapBase<typename M1::Key, typename M1::Value> {
   1.266      const M1& m1;
   1.267 @@ -613,21 +620,23 @@
   1.268      return MulMap<M1, M2>(m1,m2);
   1.269    }
   1.270   
   1.271 -  ///Scales a maps with a constant.
   1.272 +  ///Scales a map with a constant.
   1.273  
   1.274    ///This \c concepts::ReadMap "read only map" returns the value of the
   1.275    ///given map multiplied from the left side with a constant value.
   1.276 -  ///Its \c Key and \c Value is inherited from \c M.
   1.277 +  ///Its \c Key and \c Value are inherited from \c M.
   1.278    ///
   1.279    ///Actually,
   1.280    ///\code
   1.281    ///  ScaleMap<X> sc(x,v);
   1.282    ///\endcode
   1.283 -  ///is equivalent with
   1.284 +  ///is equivalent to
   1.285    ///\code
   1.286    ///  ConstMap<X::Key, X::Value> c_tmp(v);
   1.287    ///  MulMap<X, ConstMap<X::Key, X::Value> > sc(x,v);
   1.288    ///\endcode
   1.289 +  ///
   1.290 +  ///\sa ScaleWriteMap
   1.291    template<typename M, typename C = typename M::Value> 
   1.292    class ScaleMap : public MapBase<typename M::Key, typename M::Value> {
   1.293      const M& m;
   1.294 @@ -639,20 +648,23 @@
   1.295  
   1.296      ///Constructor
   1.297  
   1.298 -    ///Constructor
   1.299 -    ///\param _m is the undelying map
   1.300 -    ///\param _v is the scaling value
   1.301 +    ///Constructor.
   1.302 +    ///\param _m is the undelying map.
   1.303 +    ///\param _v is the scaling value.
   1.304      ScaleMap(const M &_m, const C &_v ) : m(_m), v(_v) {};
   1.305      /// \e
   1.306      Value operator[](Key k) const {return v * m[k];}
   1.307    };
   1.308  
   1.309 -  ///Scales a maps with a constant (ReadWrite version).
   1.310 +  ///Scales a map with a constant (ReadWrite version).
   1.311  
   1.312    ///This \c concepts::ReadWriteMap "read-write map" returns the value of the
   1.313    ///given map multiplied from the left side with a constant value. It can
   1.314 -  ///be used as write map also if the given multiplier is not zero.
   1.315 -  ///Its \c Key and \c Value is inherited from \c M.
   1.316 +  ///also be used as write map if the \c / operator is defined between
   1.317 +  ///\c Value and \c C and the given multiplier is not zero.
   1.318 +  ///Its \c Key and \c Value are inherited from \c M.
   1.319 +  ///
   1.320 +  ///\sa ScaleMap
   1.321    template<typename M, typename C = typename M::Value> 
   1.322    class ScaleWriteMap : public MapBase<typename M::Key, typename M::Value> {
   1.323      M& m;
   1.324 @@ -664,9 +676,9 @@
   1.325  
   1.326      ///Constructor
   1.327  
   1.328 -    ///Constructor
   1.329 -    ///\param _m is the undelying map
   1.330 -    ///\param _v is the scaling value
   1.331 +    ///Constructor.
   1.332 +    ///\param _m is the undelying map.
   1.333 +    ///\param _v is the scaling value.
   1.334      ScaleWriteMap(M &_m, const C &_v ) : m(_m), v(_v) {};
   1.335      /// \e
   1.336      Value operator[](Key k) const {return v * m[k];}
   1.337 @@ -674,15 +686,19 @@
   1.338      void set(Key k, const Value& c) { m.set(k, c / v);}
   1.339    };
   1.340    
   1.341 -  ///Returns an \c ScaleMap class
   1.342 +  ///Returns a \c ScaleMap class
   1.343  
   1.344 -  ///This function just returns an \c ScaleMap class.
   1.345 +  ///This function just returns a \c ScaleMap class.
   1.346    ///\relates ScaleMap
   1.347    template<typename M, typename C> 
   1.348    inline ScaleMap<M, C> scaleMap(const M &m,const C &v) {
   1.349      return ScaleMap<M, C>(m,v);
   1.350    }
   1.351  
   1.352 +  ///Returns a \c ScaleWriteMap class
   1.353 +
   1.354 +  ///This function just returns a \c ScaleWriteMap class.
   1.355 +  ///\relates ScaleWriteMap
   1.356    template<typename M, typename C> 
   1.357    inline ScaleWriteMap<M, C> scaleMap(M &m,const C &v) {
   1.358      return ScaleWriteMap<M, C>(m,v);
   1.359 @@ -691,10 +707,9 @@
   1.360    ///Quotient of two maps
   1.361  
   1.362    ///This \c concepts::ReadMap "read only map" returns the quotient of the
   1.363 -  ///values of the two
   1.364 -  ///given maps. Its \c Key and \c Value will be inherited from \c M1.
   1.365 +  ///values of the two given maps.
   1.366 +  ///Its \c Key and \c Value are inherited from \c M1.
   1.367    ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
   1.368 -
   1.369    template<typename M1, typename M2> 
   1.370    class DivMap : public MapBase<typename M1::Key, typename M1::Value> {
   1.371      const M1& m1;
   1.372 @@ -722,18 +737,19 @@
   1.373    ///Composition of two maps
   1.374  
   1.375    ///This \c concepts::ReadMap "read only map" returns the composition of
   1.376 -  ///two
   1.377 -  ///given maps. That is to say, if \c m1 is of type \c M1 and \c m2 is
   1.378 -  ///of \c M2,
   1.379 +  ///two given maps.
   1.380 +  ///That is to say, if \c m1 is of type \c M1 and \c m2 is of \c M2,
   1.381    ///then for
   1.382    ///\code
   1.383    ///  ComposeMap<M1, M2> cm(m1,m2);
   1.384    ///\endcode
   1.385 -  /// <tt>cm[x]</tt> will be equal to <tt>m1[m2[x]]</tt>
   1.386 +  /// <tt>cm[x]</tt> will be equal to <tt>m1[m2[x]]</tt>.
   1.387    ///
   1.388 -  ///Its \c Key is inherited from \c M2 and its \c Value is from
   1.389 -  ///\c M1.
   1.390 -  ///The \c M2::Value must be convertible to \c M1::Key.
   1.391 +  ///Its \c Key is inherited from \c M2 and its \c Value is from \c M1.
   1.392 +  ///\c M2::Value must be convertible to \c M1::Key.
   1.393 +  ///
   1.394 +  ///\sa CombineMap
   1.395 +  ///
   1.396    ///\todo Check the requirements.
   1.397    template <typename M1, typename M2> 
   1.398    class ComposeMap : public MapBase<typename M2::Key, typename M1::Value> {
   1.399 @@ -757,37 +773,37 @@
   1.400      typename M1::Value
   1.401      operator[](Key k) const {return m1[m2[k]];}
   1.402    };
   1.403 +
   1.404    ///Returns a \c ComposeMap class
   1.405  
   1.406    ///This function just returns a \c ComposeMap class.
   1.407 -  ///
   1.408    ///\relates ComposeMap
   1.409    template <typename M1, typename M2> 
   1.410    inline ComposeMap<M1, M2> composeMap(const M1 &m1,const M2 &m2) {
   1.411      return ComposeMap<M1, M2>(m1,m2);
   1.412    }
   1.413    
   1.414 -  ///Combines of two maps using an STL (binary) functor.
   1.415 +  ///Combine of two maps using an STL (binary) functor.
   1.416  
   1.417 -  ///Combines of two maps using an STL (binary) functor.
   1.418 -  ///
   1.419 +  ///Combine of two maps using an STL (binary) functor.
   1.420    ///
   1.421    ///This \c concepts::ReadMap "read only map" takes two maps and a
   1.422 -  ///binary functor and returns the composition of
   1.423 -  ///the two
   1.424 +  ///binary functor and returns the composition of the two
   1.425    ///given maps unsing the functor. 
   1.426    ///That is to say, if \c m1 and \c m2 is of type \c M1 and \c M2
   1.427 -  ///and \c f is of \c F,
   1.428 -  ///then for
   1.429 +  ///and \c f is of \c F, then for
   1.430    ///\code
   1.431 -  ///  CombineMap<M1, M2,F,V> cm(m1,m2,f);
   1.432 +  ///  CombineMap<M1,M2,F,V> cm(m1,m2,f);
   1.433    ///\endcode
   1.434    /// <tt>cm[x]</tt> will be equal to <tt>f(m1[x],m2[x])</tt>
   1.435    ///
   1.436    ///Its \c Key is inherited from \c M1 and its \c Value is \c V.
   1.437 -  ///The \c M2::Value and \c M1::Value must be convertible to the corresponding
   1.438 +  ///\c M2::Value and \c M1::Value must be convertible to the corresponding
   1.439    ///input parameter of \c F and the return type of \c F must be convertible
   1.440    ///to \c V.
   1.441 +  ///
   1.442 +  ///\sa ComposeMap
   1.443 +  ///
   1.444    ///\todo Check the requirements.
   1.445    template<typename M1, typename M2, typename F,
   1.446  	   typename V = typename F::result_type> 
   1.447 @@ -815,13 +831,13 @@
   1.448    ///\code
   1.449    ///combineMap<double>(m1,m2,std::plus<double>())
   1.450    ///\endcode
   1.451 -  ///is equivalent with
   1.452 +  ///is equivalent to
   1.453    ///\code
   1.454    ///addMap(m1,m2)
   1.455    ///\endcode
   1.456    ///
   1.457    ///This function is specialized for adaptable binary function
   1.458 -  ///classes and c++ functions.
   1.459 +  ///classes and C++ functions.
   1.460    ///
   1.461    ///\relates CombineMap
   1.462    template<typename M1, typename M2, typename F, typename V> 
   1.463 @@ -845,11 +861,11 @@
   1.464    ///Negative value of a map
   1.465  
   1.466    ///This \c concepts::ReadMap "read only map" returns the negative
   1.467 -  ///value of the
   1.468 -  ///value returned by the
   1.469 -  ///given map. Its \c Key and \c Value will be inherited from \c M.
   1.470 +  ///value of the value returned by the given map.
   1.471 +  ///Its \c Key and \c Value are inherited from \c M.
   1.472    ///The unary \c - operator must be defined for \c Value, of course.
   1.473 -
   1.474 +  ///
   1.475 +  ///\sa NegWriteMap
   1.476    template<typename M> 
   1.477    class NegMap : public MapBase<typename M::Key, typename M::Value> {
   1.478      const M& m;
   1.479 @@ -867,10 +883,11 @@
   1.480    ///Negative value of a map (ReadWrite version)
   1.481  
   1.482    ///This \c concepts::ReadWriteMap "read-write map" returns the negative
   1.483 -  ///value of the value returned by the
   1.484 -  ///given map. Its \c Key and \c Value will be inherited from \c M.
   1.485 +  ///value of the value returned by the given map.
   1.486 +  ///Its \c Key and \c Value are inherited from \c M.
   1.487    ///The unary \c - operator must be defined for \c Value, of course.
   1.488 -
   1.489 +  ///
   1.490 +  /// \sa NegMap
   1.491    template<typename M> 
   1.492    class NegWriteMap : public MapBase<typename M::Key, typename M::Value> {
   1.493      M& m;
   1.494 @@ -896,6 +913,10 @@
   1.495      return NegMap<M>(m);
   1.496    }
   1.497  
   1.498 +  ///Returns a \c NegWriteMap class
   1.499 +
   1.500 +  ///This function just returns a \c NegWriteMap class.
   1.501 +  ///\relates NegWriteMap
   1.502    template <typename M> 
   1.503    inline NegWriteMap<M> negMap(M &m) {
   1.504      return NegWriteMap<M>(m);
   1.505 @@ -904,14 +925,10 @@
   1.506    ///Absolute value of a map
   1.507  
   1.508    ///This \c concepts::ReadMap "read only map" returns the absolute value
   1.509 -  ///of the
   1.510 -  ///value returned by the
   1.511 -  ///given map. Its \c Key and \c Value will be inherited
   1.512 -  ///from <tt>M</tt>. <tt>Value</tt>
   1.513 -  ///must be comparable to <tt>0</tt> and the unary <tt>-</tt>
   1.514 +  ///of the value returned by the given map.
   1.515 +  ///Its \c Key and \c Value are inherited from \c M. 
   1.516 +  ///\c Value must be comparable to \c 0 and the unary \c -
   1.517    ///operator must be defined for it, of course.
   1.518 -  ///
   1.519 -
   1.520    template<typename M> 
   1.521    class AbsMap : public MapBase<typename M::Key, typename M::Value> {
   1.522      const M& m;
   1.523 @@ -930,9 +947,9 @@
   1.524  
   1.525    };
   1.526    
   1.527 -  ///Returns a \c AbsMap class
   1.528 +  ///Returns an \c AbsMap class
   1.529  
   1.530 -  ///This function just returns a \c AbsMap class.
   1.531 +  ///This function just returns an \c AbsMap class.
   1.532    ///\relates AbsMap
   1.533    template<typename M> 
   1.534    inline AbsMap<M> absMap(const M &m) {
   1.535 @@ -942,14 +959,15 @@
   1.536    ///Converts an STL style functor to a map
   1.537  
   1.538    ///This \c concepts::ReadMap "read only map" returns the value
   1.539 -  ///of a
   1.540 -  ///given map.
   1.541 +  ///of a given functor.
   1.542    ///
   1.543    ///Template parameters \c K and \c V will become its
   1.544 -  ///\c Key and \c Value. They must be given explicitely
   1.545 +  ///\c Key and \c Value. They must be given explicitly
   1.546    ///because a functor does not provide such typedefs.
   1.547    ///
   1.548    ///Parameter \c F is the type of the used functor.
   1.549 +  ///
   1.550 +  ///\sa MapFunctor
   1.551    template<typename F, 
   1.552  	   typename K = typename F::argument_type, 
   1.553  	   typename V = typename F::result_type> 
   1.554 @@ -971,7 +989,7 @@
   1.555    ///This function just returns a \c FunctorMap class.
   1.556    ///
   1.557    ///It is specialized for adaptable function classes and
   1.558 -  ///c++ functions.
   1.559 +  ///C++ functions.
   1.560    ///\relates FunctorMap
   1.561    template<typename K, typename V, typename F> inline 
   1.562    FunctorMap<F, K, V> functorMap(const F &f) {
   1.563 @@ -999,6 +1017,8 @@
   1.564    ///For the sake of convenience it also works as
   1.565    ///a ususal \c concepts::ReadMap "readable map",
   1.566    ///i.e. <tt>operator[]</tt> and the \c Key and \c Value typedefs also exist.
   1.567 +  ///
   1.568 +  ///\sa FunctorMap
   1.569    template <typename M> 
   1.570    class MapFunctor : public MapBase<typename M::Key, typename M::Value> {
   1.571      const M& m;
   1.572 @@ -1033,9 +1053,11 @@
   1.573    ///parameters and each read request will be passed just to the
   1.574    ///first map. This class is the just readable map type of the ForkWriteMap.
   1.575    ///
   1.576 -  ///The \c Key and \c Value will be inherited from \c M1.
   1.577 +  ///The \c Key and \c Value are inherited from \c M1.
   1.578    ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
   1.579    ///
   1.580 +  ///\sa ForkWriteMap
   1.581 +  ///
   1.582    /// \todo Why is it needed?
   1.583    template<typename  M1, typename M2> 
   1.584    class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
   1.585 @@ -1061,8 +1083,10 @@
   1.586    ///then the read operations will return the
   1.587    ///corresponding values of \c M1.
   1.588    ///
   1.589 -  ///The \c Key and \c Value will be inherited from \c M1.
   1.590 +  ///The \c Key and \c Value are inherited from \c M1.
   1.591    ///The \c Key and \c Value of M2 must be convertible from those of \c M1.
   1.592 +  ///
   1.593 +  ///\sa ForkMap
   1.594    template<typename  M1, typename M2> 
   1.595    class ForkWriteMap : public MapBase<typename M1::Key, typename M1::Value> {
   1.596      M1& m1;
   1.597 @@ -1080,16 +1104,19 @@
   1.598      void set(Key k, const Value &v) {m1.set(k,v); m2.set(k,v);}
   1.599    };
   1.600    
   1.601 -  ///Returns an \c ForkMap class
   1.602 +  ///Returns a \c ForkMap class
   1.603  
   1.604 -  ///This function just returns an \c ForkMap class.
   1.605 -  ///
   1.606 +  ///This function just returns a \c ForkMap class.
   1.607    ///\relates ForkMap
   1.608    template <typename M1, typename M2> 
   1.609    inline ForkMap<M1, M2> forkMap(const M1 &m1, const M2 &m2) {
   1.610      return ForkMap<M1, M2>(m1,m2);
   1.611    }
   1.612  
   1.613 +  ///Returns a \c ForkWriteMap class
   1.614 +
   1.615 +  ///This function just returns a \c ForkWriteMap class.
   1.616 +  ///\relates ForkWriteMap
   1.617    template <typename M1, typename M2> 
   1.618    inline ForkWriteMap<M1, M2> forkMap(M1 &m1, M2 &m2) {
   1.619      return ForkWriteMap<M1, M2>(m1,m2);
   1.620 @@ -1102,10 +1129,10 @@
   1.621    ///Logical 'not' of a map
   1.622    
   1.623    ///This bool \c concepts::ReadMap "read only map" returns the 
   1.624 -  ///logical negation of
   1.625 -  ///value returned by the
   1.626 -  ///given map. Its \c Key and will be inherited from \c M,
   1.627 -  ///its Value is <tt>bool</tt>.
   1.628 +  ///logical negation of the value returned by the given map.
   1.629 +  ///Its \c Key is inherited from \c M, its Value is \c bool.
   1.630 +  ///
   1.631 +  ///\sa NotWriteMap
   1.632    template <typename M> 
   1.633    class NotMap : public MapBase<typename M::Key, bool> {
   1.634      const M& m;
   1.635 @@ -1123,10 +1150,11 @@
   1.636    ///Logical 'not' of a map (ReadWrie version)
   1.637    
   1.638    ///This bool \c concepts::ReadWriteMap "read-write map" returns the 
   1.639 -  ///logical negation of value returned by the given map. When it is set,
   1.640 +  ///logical negation of the value returned by the given map. When it is set,
   1.641    ///the opposite value is set to the original map.
   1.642 -  ///Its \c Key and will be inherited from \c M,
   1.643 -  ///its Value is <tt>bool</tt>.
   1.644 +  ///Its \c Key is inherited from \c M, its Value is \c bool.
   1.645 +  ///
   1.646 +  ///\sa NotMap
   1.647    template <typename M> 
   1.648    class NotWriteMap : public MapBase<typename M::Key, bool> {
   1.649      M& m;
   1.650 @@ -1152,6 +1180,10 @@
   1.651      return NotMap<M>(m);
   1.652    }
   1.653    
   1.654 +  ///Returns a \c NotWriteMap class
   1.655 +  
   1.656 +  ///This function just returns a \c NotWriteMap class.
   1.657 +  ///\relates NotWriteMap
   1.658    template <typename M> 
   1.659    inline NotWriteMap<M> notMap(M &m) {
   1.660      return NotWriteMap<M>(m);
   1.661 @@ -1183,10 +1215,10 @@
   1.662    }
   1.663    
   1.664  
   1.665 -  /// \brief Writable bool map for logging each true assigned elements
   1.666 +  /// \brief Writable bool map for logging each \c true assigned element
   1.667    ///
   1.668 -  /// Writable bool map for logging each true assigned elements, i.e it
   1.669 -  /// copies all the keys set to true to the given iterator.
   1.670 +  /// Writable bool map for logging each \c true assigned element, i.e it
   1.671 +  /// copies all the keys set to \c true to the given iterator.
   1.672    ///
   1.673    /// \note The container of the iterator should contain space 
   1.674    /// for each element.
   1.675 @@ -1207,7 +1239,9 @@
   1.676    /// prim(graph, cost, writerMap);
   1.677    ///\endcode
   1.678    ///
   1.679 -  ///\todo Revise the name of this class and the relates ones.
   1.680 +  ///\sa BackInserterBoolMap 
   1.681 +  ///
   1.682 +  ///\todo Revise the name of this class and the related ones.
   1.683    template <typename _Iterator, 
   1.684              typename _Functor =
   1.685              _maps_bits::Identity<typename _maps_bits::
   1.686 @@ -1235,7 +1269,7 @@
   1.687        return _end;
   1.688      }
   1.689  
   1.690 -    /// Setter function of the map
   1.691 +    /// The \c set function of the map
   1.692      void set(const Key& key, Value value) const {
   1.693        if (value) {
   1.694  	*_end++ = _functor(key);
   1.695 @@ -1248,11 +1282,11 @@
   1.696      Functor _functor;
   1.697    };
   1.698  
   1.699 -  /// \brief Writable bool map for logging each true assigned elements in 
   1.700 -  /// a back insertable container
   1.701 +  /// \brief Writable bool map for logging each \c true assigned element in 
   1.702 +  /// a back insertable container.
   1.703    ///
   1.704 -  /// Writable bool map for logging each true assigned elements by pushing
   1.705 -  /// back them into a back insertable container.
   1.706 +  /// Writable bool map for logging each \c true assigned element by pushing
   1.707 +  /// them into a back insertable container.
   1.708    /// It can be used to retrieve the items into a standard
   1.709    /// container. The next example shows how you can store the
   1.710    /// edges found by the Prim algorithm in a vector.
   1.711 @@ -1262,6 +1296,10 @@
   1.712    /// BackInserterBoolMap<vector<Edge> > inserter_map(span_tree_edges);
   1.713    /// prim(graph, cost, inserter_map);
   1.714    ///\endcode
   1.715 +  ///
   1.716 +  ///\sa StoreBoolMap
   1.717 +  ///\sa FrontInserterBoolMap
   1.718 +  ///\sa InserterBoolMap
   1.719    template <typename Container,
   1.720              typename Functor =
   1.721              _maps_bits::Identity<typename Container::value_type> >
   1.722 @@ -1275,7 +1313,7 @@
   1.723                          const Functor& _functor = Functor()) 
   1.724        : container(_container), functor(_functor) {}
   1.725  
   1.726 -    /// Setter function of the map
   1.727 +    /// The \c set function of the map
   1.728      void set(const Key& key, Value value) {
   1.729        if (value) {
   1.730  	container.push_back(functor(key));
   1.731 @@ -1287,12 +1325,16 @@
   1.732      Functor functor;
   1.733    };
   1.734  
   1.735 -  /// \brief Writable bool map for storing each true assignments in 
   1.736 +  /// \brief Writable bool map for logging each \c true assigned element in 
   1.737    /// a front insertable container.
   1.738    ///
   1.739 -  /// Writable bool map for storing each true assignment in a front 
   1.740 -  /// insertable container. It will push front all the keys set to \c true into
   1.741 -  /// the container. For example see the BackInserterBoolMap.
   1.742 +  /// Writable bool map for logging each \c true assigned element by pushing
   1.743 +  /// them into a front insertable container.
   1.744 +  /// It can be used to retrieve the items into a standard
   1.745 +  /// container. For example see \ref BackInserterBoolMap.
   1.746 +  ///
   1.747 +  ///\sa BackInserterBoolMap
   1.748 +  ///\sa InserterBoolMap
   1.749    template <typename Container,
   1.750              typename Functor =
   1.751              _maps_bits::Identity<typename Container::value_type> >
   1.752 @@ -1306,7 +1348,7 @@
   1.753                           const Functor& _functor = Functor()) 
   1.754        : container(_container), functor(_functor) {}
   1.755  
   1.756 -    /// Setter function of the map
   1.757 +    /// The \c set function of the map
   1.758      void set(const Key& key, Value value) {
   1.759        if (value) {
   1.760  	container.push_front(key);
   1.761 @@ -1318,10 +1360,10 @@
   1.762      Functor functor;
   1.763    };
   1.764  
   1.765 -  /// \brief Writable bool map for storing each true assigned elements in 
   1.766 +  /// \brief Writable bool map for storing each \c true assigned element in 
   1.767    /// an insertable container.
   1.768    ///
   1.769 -  /// Writable bool map for storing each true assigned elements in an 
   1.770 +  /// Writable bool map for storing each \c true assigned element in an 
   1.771    /// insertable container. It will insert all the keys set to \c true into
   1.772    /// the container.
   1.773    ///
   1.774 @@ -1333,6 +1375,9 @@
   1.775    /// InserterBoolMap<set<Arc> > inserter_map(cut_arcs);
   1.776    /// stronglyConnectedCutArcs(digraph, cost, inserter_map);
   1.777    ///\endcode
   1.778 +  ///
   1.779 +  ///\sa BackInserterBoolMap
   1.780 +  ///\sa FrontInserterBoolMap
   1.781    template <typename Container,
   1.782              typename Functor =
   1.783              _maps_bits::Identity<typename Container::value_type> >
   1.784 @@ -1341,16 +1386,26 @@
   1.785      typedef typename Container::value_type Key;
   1.786      typedef bool Value;
   1.787  
   1.788 -    /// Constructor
   1.789 +    /// Constructor with specified iterator
   1.790 +    
   1.791 +    /// Constructor with specified iterator.
   1.792 +    /// \param _container The container for storing the elements.
   1.793 +    /// \param _it The elements will be inserted before this iterator.
   1.794 +    /// \param _functor The functor that is used when an element is stored.
   1.795      InserterBoolMap(Container& _container, typename Container::iterator _it,
   1.796                      const Functor& _functor = Functor()) 
   1.797        : container(_container), it(_it), functor(_functor) {}
   1.798  
   1.799      /// Constructor
   1.800 +
   1.801 +    /// Constructor without specified iterator.
   1.802 +    /// The elements will be inserted before <tt>_container.end()</tt>.
   1.803 +    /// \param _container The container for storing the elements.
   1.804 +    /// \param _functor The functor that is used when an element is stored.
   1.805      InserterBoolMap(Container& _container, const Functor& _functor = Functor())
   1.806        : container(_container), it(_container.end()), functor(_functor) {}
   1.807  
   1.808 -    /// Setter function of the map
   1.809 +    /// The \c set function of the map
   1.810      void set(const Key& key, Value value) {
   1.811        if (value) {
   1.812  	it = container.insert(it, key);
   1.813 @@ -1364,11 +1419,11 @@
   1.814      Functor functor;
   1.815    };
   1.816  
   1.817 -  /// \brief Fill the true set elements with a given value.
   1.818 +  /// \brief Writable bool map for filling each \c true assigned element with a 
   1.819 +  /// given value.
   1.820    ///
   1.821 -  /// Writable bool map to fill the elements set to \c true with a given value.
   1.822 -  /// The value can set 
   1.823 -  /// the container.
   1.824 +  /// Writable bool map for filling each \c true assigned element with a 
   1.825 +  /// given value. The value can set the container.
   1.826    ///
   1.827    /// The following code finds the connected components of a graph
   1.828    /// and stores it in the \c comp map:
   1.829 @@ -1418,7 +1473,7 @@
   1.830        fill = _fill;
   1.831      } 
   1.832  
   1.833 -    /// Set function of the map
   1.834 +    /// The \c set function of the map
   1.835      void set(const Key& key, Value value) {
   1.836        if (value) {
   1.837  	map.set(key, fill);
   1.838 @@ -1431,10 +1486,10 @@
   1.839    };
   1.840  
   1.841  
   1.842 -  /// \brief Writable bool map which stores the sequence number of 
   1.843 -  /// true assignments.  
   1.844 +  /// \brief Writable bool map for storing the sequence number of 
   1.845 +  /// \c true assignments.  
   1.846    /// 
   1.847 -  /// Writable bool map which stores for each true assigned elements  
   1.848 +  /// Writable bool map that stores for each \c true assigned elements  
   1.849    /// the sequence number of this setting.
   1.850    /// It makes it easy to calculate the leaving
   1.851    /// order of the nodes in the \c Dfs algorithm.