Index: lemon/graph_utils.h
===================================================================
--- lemon/graph_utils.h	(revision 1538)
+++ lemon/graph_utils.h	(revision 1540)
@@ -31,6 +31,4 @@
 ///\brief Graph utilities.
 ///
-///\todo Please
-///revise the documentation.
 ///
 
@@ -43,5 +41,5 @@
   /// \brief Function to count the items in the graph.
   ///
-  /// This function counts the items in the graph.
+  /// This function counts the items (nodes, edges etc) in the graph.
   /// The complexity of the function is O(n) because
   /// it iterates on all of the items.
@@ -126,5 +124,5 @@
   /// This function counts the undirected edges in the graph.
   /// The complexity of the function is O(e) but for some
-  /// graph structure it is specialized to run in O(1).
+  /// graph structures it is specialized to run in O(1).
 
   template <typename Graph>
@@ -194,9 +192,9 @@
   }
 
-  /// \brief Copy the source map to the target map.
-  ///
-  /// Copy the \c source map to the \c target map. It uses the given iterator
-  /// to iterate on the data structure and it use the \c ref mapping to
-  /// convert the source's keys to the target's keys.
+  /// \brief Copy a map.
+  ///
+  /// Thsi function copies the \c source map to the \c target map. It uses the
+  /// given iterator to iterate on the data structure and it uses the \c ref
+  /// mapping to convert the source's keys to the target's keys.
   template <typename Target, typename Source, 
 	    typename ItemIt, typename Ref>	    
@@ -221,8 +219,8 @@
 
 
-  /// \brief Class to copy a graph to an other graph.
-  ///
-  /// Class to copy a graph to an other graph. It can be used easier
-  /// with the \c copyGraph() function.
+  /// \brief Class to copy a graph.
+  ///
+  /// Class to copy a graph to an other graph (duplicate a graph). The
+  /// simplest way of using it is through the \c copyGraph() function.
   template <typename Target, typename Source>
   class GraphCopy {
@@ -355,5 +353,5 @@
   /// After the copy the \c nr map will contain the mapping from the
   /// source graph's nodes to the target graph's nodes and the \c ecr will
-  /// contain the mapping from the target graph's edge to the source's
+  /// contain the mapping from the target graph's edges to the source's
   /// edges.
   template <typename Target, typename Source>
@@ -459,6 +457,11 @@
   /// Provides an immutable and unique id for each item in the graph.
 
-  /// The IdMap class provides a unique and immutable mapping for each item
-  /// in the graph.
+  /// The IdMap class provides a unique and immutable id for each item of the
+  /// same type (e.g. node) in the graph. This id is <ul><li>\b unique:
+  /// different items (nodes) get different ids <li>\b immutable: the id of an
+  /// item (node) does not change (even if you delete other nodes).  </ul>
+  /// Through this map you get access (i.e. can read) the inner id values of
+  /// the items stored in the graph. This map can be inverted with its member
+  /// class \c InverseMap.
   ///
   template <typename _Graph, typename _Item>
@@ -488,7 +491,7 @@
   public:
 
-    /// \brief The class represents the inverse of the map.
-    ///
-    /// The class represents the inverse of the map.
+    /// \brief The class represents the inverse of its owner (IdMap).
+    ///
+    /// The class represents the inverse of its owner (IdMap).
     /// \see inverse()
     class InverseMap {
@@ -518,5 +521,5 @@
     /// \brief Gives back the inverse of the map.
     ///
-    /// Gives back the inverse of the map.
+    /// Gives back the inverse of the IdMap.
     InverseMap inverse() const { return InverseMap(*graph);} 
 
@@ -526,5 +529,5 @@
   /// \brief General invertable graph-map type.
 
-  /// This type provides simple invertable map functions. 
+  /// This type provides simple invertable graph-maps. 
   /// The InvertableMap wraps an arbitrary ReadWriteMap 
   /// and if a key is set to a new value then store it
@@ -659,7 +662,12 @@
   /// item in the graph.
   ///
-  /// The DescriptorMap class provides a mutable, continuous and immutable
-  /// mapping for each item in the graph. The value for an item may mutated
-  /// on each operation when the an item erased or added to graph.
+  /// The DescriptorMap class provides a unique and continuous (but mutable)
+  /// descriptor (id) for each item of the same type (e.g. node) in the
+  /// graph. This id is <ul><li>\b unique: different items (nodes) get
+  /// different ids <li>\b continuous: the range of the ids is the set of
+  /// integers between 0 and \c n-1, where \c n is the number of the items of
+  /// this type (e.g. nodes) (so the id of a node can change if you delete an
+  /// other node, i.e. this id is mutable).  </ul> This map can be inverted
+  /// with its member class \c InverseMap.
   ///
   /// \param _Graph The graph class the \c DescriptorMap belongs to.
@@ -755,7 +763,7 @@
 
   public:
-    /// \brief The inverse map type.
-    ///
-    /// The inverse map type.
+    /// \brief The inverse map type of DescriptorMap.
+    ///
+    /// The inverse map type of DescriptorMap.
     class InverseMap {
     public:
@@ -874,5 +882,5 @@
   /// \brief Returns a \ref TargetMap class
   ///
-  /// This function just returns an \ref TargetMap class.
+  /// This function just returns a \ref TargetMap class.
   /// \relates TargetMap
   template <typename Graph>
@@ -881,7 +889,7 @@
   }
 
-  /// \brief Returns the "forward" directed edge view of undirected edge.
-  ///
-  /// Returns the "forward" directed edge view of undirected edge.
+  /// \brief Returns the "forward" directed edge view of an undirected edge.
+  ///
+  /// Returns the "forward" directed edge view of an undirected edge.
   /// \author Balazs Dezso
   template <typename Graph>
@@ -922,7 +930,7 @@
   }
 
-  /// \brief Returns the "backward" directed edge view of undirected edge.
-  ///
-  /// Returns the "backward" directed edge view of undirected edge.
+  /// \brief Returns the "backward" directed edge view of an undirected edge.
+  ///
+  /// Returns the "backward" directed edge view of an undirected edge.
   /// \author Balazs Dezso
   template <typename Graph>
@@ -955,5 +963,5 @@
   /// \brief Returns a \ref BackwardMap class
 
-  /// This function just returns an \ref BackwardMap class.
+  /// This function just returns a \ref BackwardMap class.
   /// \relates BackwardMap
   template <typename Graph>
@@ -976,7 +984,7 @@
   /// \brief Map of the node in-degrees.
   ///
-  /// This map returns the in-degree of a node. Ones it is constructed,
+  /// This map returns the in-degree of a node. Once it is constructed,
   /// the degrees are stored in a standard NodeMap, so each query is done
-  /// in constant time. On the other hand, the values updates automatically
+  /// in constant time. On the other hand, the values are updated automatically
   /// whenever the graph changes.
   ///
@@ -1068,7 +1076,7 @@
   /// \brief Map of the node out-degrees.
   ///
-  /// This map returns the out-degree of a node. One it is constructed,
+  /// This map returns the out-degree of a node. Once it is constructed,
   /// the degrees are stored in a standard NodeMap, so each query is done
-  /// in constant time. On the other hand, the values updates automatically
+  /// in constant time. On the other hand, the values are updated automatically
   /// whenever the graph changes.
   ///
