# HG changeset patch
# User Alpar Juttner <alpar@cs.elte.hu>
# Date 1198332262 0
# Node ID 61bf7f22a6d64c045d47280a75b3481c0d729e27
# Parent  751cd8f9bb1c4bc2d28581ea7c66ef72e37b8da1
Several doc improvements in maps.h

diff -r 751cd8f9bb1c -r 61bf7f22a6d6 lemon/concept_check.h
--- a/lemon/concept_check.h	Sat Dec 22 12:35:00 2007 +0000
+++ b/lemon/concept_check.h	Sat Dec 22 14:04:22 2007 +0000
@@ -16,10 +16,10 @@
  *
  */
 
-// Modified for use in LEMON.
-// We should really consider using Boost...
+// This file contains a modified version of the concept checking
+// utility from BOOST.
+// See the appropriate copyright notice below.
 
-//
 // (C) Copyright Jeremy Siek 2000.
 // Distributed under the Boost Software License, Version 1.0. (See
 // accompanying file LICENSE_1_0.txt or copy at
diff -r 751cd8f9bb1c -r 61bf7f22a6d6 lemon/maps.h
--- a/lemon/maps.h	Sat Dec 22 12:35:00 2007 +0000
+++ b/lemon/maps.h	Sat Dec 22 14:04:22 2007 +0000
@@ -247,7 +247,9 @@
   /// The current map has the \c [0..size-1] 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.
+  /// the used items are small integer numbers. 
+  ///
+  /// \todo Revise its name
   template <typename T>
   class IntegerMap {
 
@@ -346,8 +348,9 @@
   }
   
 
-  ///Convert the \c Value of a map to another type.
-
+  ///\brief Convert the \c Value of a map to another type using
+  ///the default conversion.
+  ///
   ///This \c concepts::ReadMap "read only map"
   ///converts the \c Value of a maps to type \c T.
   ///Its \c Key is inherited from \c M.
@@ -368,8 +371,6 @@
     /// \brief The subscript operator.
     ///
     /// The subscript operator.
-    /// \param k The key
-    /// \return The target of the arc 
     Value operator[](const Key& k) const {return m[k];}
   };
   
@@ -388,6 +389,8 @@
   ///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.
+  ///
+  /// \todo Revise the misleading name
   template<typename M> 
   class SimpleMap : public MapBase<typename M::Key, typename M::Value> {
     const M& m;
@@ -405,10 +408,12 @@
 
   ///Simple writeable wrapping of the map
 
-  ///This \c concepts::ReadMap "read only map" returns the simple
+  ///This \c concepts::WriteMap "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.
+  ///
+  /// \todo Revise the misleading name
   template<typename M> 
   class SimpleWriteMap : public MapBase<typename M::Key, typename M::Value> {
     M& m;
@@ -493,7 +498,7 @@
     Value operator[](Key k) const {return m[k] + v;}
   };
 
-  ///Shift a map with a constant.
+  ///Shift a map with a constant. This map is also writable.
 
   ///This \c concepts::ReadWriteMap "read-write map" returns the sum of the
   ///given map and a constant value. It makes also possible to write the map.
@@ -549,7 +554,8 @@
   ///of the values of the two
   ///given maps. Its \c Key and \c Value will be inherited from \c M1.
   ///The \c Key and \c Value of \c M2 must be convertible to those of \c M1.
-
+  ///
+  /// \todo Revise the misleading name
   template<typename M1, typename M2> 
   class SubMap : public MapBase<typename M1::Key, typename M1::Value> {
     const M1& m1;
@@ -641,7 +647,7 @@
     Value operator[](Key k) const {return v * m[k];}
   };
 
-  ///Scales a maps with a constant.
+  ///Scales a maps with a constant (ReadWrite version).
 
   ///This \c concepts::ReadWriteMap "read-write map" returns the value of the
   ///given map multiplied from the left side with a constant value. It can
@@ -858,7 +864,7 @@
     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
@@ -905,18 +911,6 @@
   ///must be comparable to <tt>0</tt> and the unary <tt>-</tt>
   ///operator must be defined for it, of course.
   ///
-  ///\bug We need a unified way to handle the situation below:
-  ///\code
-  ///  struct _UnConvertible {};
-  ///  template<class A> inline A t_abs(A a) {return _UnConvertible();}
-  ///  template<> inline int t_abs<>(int n) {return abs(n);}
-  ///  template<> inline long int t_abs<>(long int n) {return labs(n);}
-  ///  template<> inline long long int t_abs<>(long long int n) {return ::llabs(n);}
-  ///  template<> inline float t_abs<>(float n) {return fabsf(n);}
-  ///  template<> inline double t_abs<>(double n) {return fabs(n);}
-  ///  template<> inline long double t_abs<>(long double n) {return fabsl(n);}
-  ///\endcode
-  
 
   template<typename M> 
   class AbsMap : public MapBase<typename M::Key, typename M::Value> {
@@ -1041,6 +1035,8 @@
   ///
   ///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.
+  ///
+  /// \todo Why is it needed?
   template<typename  M1, typename M2> 
   class ForkMap : public MapBase<typename M1::Key, typename M1::Value> {
     const M1& m1;
@@ -1124,7 +1120,7 @@
     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,
@@ -1187,15 +1183,16 @@
   }
   
 
-  /// \brief Writable bool map for store each true assigned elements.
+  /// \brief Writable bool map for logging each true assigned elements
   ///
-  /// Writable bool map to store each true assigned elements. It will
+  /// Writable bool map for logging each true assigned elements, i.e it
   /// copies all the keys set to 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
+  /// The following example shows how you can write the edges found by the Prim
+  /// algorithm directly
   /// to the standard output.
   ///\code
   /// typedef IdMap<Graph, Edge> EdgeIdMap;
@@ -1209,6 +1206,8 @@
   ///
   /// prim(graph, cost, writerMap);
   ///\endcode
+  ///
+  ///\todo Revise the name of this class and the relates ones.
   template <typename _Iterator, 
             typename _Functor =
             _maps_bits::Identity<typename _maps_bits::
@@ -1226,12 +1225,12 @@
     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;
     }
@@ -1249,14 +1248,14 @@
     Functor _functor;
   };
 
-  /// \brief Writable bool map for store each true assigned elements in 
-  /// a back insertable container.
+  /// \brief Writable bool map for logging each true assigned elements 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
-  /// arcs in a vector with prim algorithm.
+  /// Writable bool map for logging each true assigned elements by pushing
+  /// back 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<Edge> span_tree_edges;
@@ -1288,10 +1287,10 @@
     Functor functor;
   };
 
-  /// \brief Writable bool map for store each true assigned elements in 
+  /// \brief Writable bool map for storing each true assignments in 
   /// a front insertable container.
   ///
-  /// Writable bool map for store each true assigned elements in a front 
+  /// Writable bool map for storing each true assignment in a front 
   /// insertable container. It will push front all the keys set to \c true into
   /// the container. For example see the BackInserterBoolMap.
   template <typename Container,
@@ -1319,12 +1318,14 @@
     Functor functor;
   };
 
-  /// \brief Writable bool map for store each true assigned elements in 
+  /// \brief Writable bool map for storing each true assigned elements in 
   /// an insertable container.
   ///
-  /// Writable bool map for store each true assigned elements in an 
+  /// Writable bool map for storing each true assigned elements in an 
   /// insertable container. It will insert all the keys set to \c true into
-  /// the container. If you want to store the cut arcs 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
@@ -1369,7 +1370,7 @@
   /// The value can set 
   /// the container.
   ///
-  /// The next code finds the connected components of the undirected digraph
+  /// The following code finds the connected components of a graph
   /// and stores it in the \c comp map:
   ///\code
   /// typedef Graph::NodeMap<int> ComponentMap;
@@ -1417,7 +1418,7 @@
       fill = _fill;
     } 
 
-    /// Setter function of the map
+    /// Set function of the map
     void set(const Key& key, Value value) {
       if (value) {
 	map.set(key, fill);
@@ -1430,11 +1431,12 @@
   };
 
 
-  /// \brief Writable bool map which stores for each true assigned elements  
-  /// the setting order number.
-  ///
+  /// \brief Writable bool map which stores the sequence number of 
+  /// true assignments.  
+  /// 
   /// Writable bool map which stores for each true assigned elements  
-  /// the setting order number. It make easy to calculate the leaving
+  /// the sequence number of this setting.
+  /// It makes it easy to calculate the leaving
   /// order of the nodes in the \c Dfs algorithm.
   ///
   ///\code
@@ -1453,9 +1455,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 Digraph::NodeMap<int> OrderMap;