[Lemon-commits] [lemon_svn] deba: r3001 - hugo/trunk/lemon

[Lemon SVN]

Author: deba
Date: Tue Oct 17 13:02:05 2006
New Revision: 3001

Modified:
   hugo/trunk/lemon/graph_adaptor.h

Log:
Documentation for UndirGraphAdaptor



Modified: hugo/trunk/lemon/graph_adaptor.h
==============================================================================
--- hugo/trunk/lemon/graph_adaptor.h	(original)
+++ hugo/trunk/lemon/graph_adaptor.h	Tue Oct 17 13:02:05 2006
@@ -1276,10 +1276,47 @@
   ///
   /// \brief An undirected graph is made from a directed graph by an adaptor
   ///
-  /// Undocumented, untested!!!
-  /// If somebody knows nice demo application, let's polulate it.
+  /// This adaptor makes an undirected graph from a directed
+  /// graph. All edge of the underlying will be showed in the adaptor
+  /// as an undirected edge. Let's see an informal example about using
+  /// this adaptor:
+  ///
+  /// There is a network of the streets of a town. Of course there are
+  /// some one-way street in the town hence the network is a directed
+  /// one. There is a crazy driver who go oppositely in the one-way
+  /// street without moral sense. Of course he can pass this streets
+  /// slower than the regular way, in fact his speed is half of the
+  /// normal speed. How long should he drive to get from a source
+  /// point to the target? Let see the example code which calculate it:
+  ///
+  ///\code
+  /// typedef UndirGraphAdaptor<Graph> UGraph;
+  /// UGraph ugraph(graph);
+  ///
+  /// typedef SimpleMap<LengthMap> FLengthMap;
+  /// FLengthMap flength(length);
+  ///
+  /// typedef ScaleMap<LengthMap> RLengthMap;
+  /// RLengthMap rlength(length, 2.0);
+  ///
+  /// typedef UGraph::CombinedEdgeMap<FLengthMap, RLengthMap > ULengthMap;
+  /// ULengthMap ulength(flength, rlength);
   /// 
-  /// \author Marton Makai
+  /// Dijkstra<UGraph, ULengthMap> dijkstra(ugraph, ulength);
+  /// std::cout << "Driving time : " << dijkstra.run(src, trg) << std::endl;
+  ///\endcode
+  ///
+  /// The combined edge map makes the length map for the undirected
+  /// graph. It is created from a forward and reverse map. The forward
+  /// map is created from the original length map with a SimpleMap
+  /// adaptor which just makes a read-write map from the reference map
+  /// i.e. it forgets that it can be return reference to values. The
+  /// reverse map is just the scaled original map with the ScaleMap
+  /// adaptor. The combination solves that passing the reverse way
+  /// takes double time than the original. To get the driving time we
+  /// run the dijkstra algorithm on the undirected graph.
+  ///
+  /// \author Marton Makai and Balazs Dezso
   template<typename _Graph>
   class UndirGraphAdaptor : public AlterableUndirGraphAdaptor<_Graph> {
   public:
@@ -1288,10 +1325,18 @@
   protected:
     UndirGraphAdaptor() { }
   public:
+
+    /// \brief Constructor
+    ///
+    /// Constructor
     UndirGraphAdaptor(_Graph& _graph) { 
       setGraph(_graph);
     }
 
+    /// \brief EdgeMap combined from two original EdgeMap
+    ///
+    /// This class adapts two original graph EdgeMap to
+    /// get an edge map on the adaptor.
     template <typename _ForwardMap, typename _BackwardMap>
     class CombinedEdgeMap {
     public:
@@ -1303,12 +1348,22 @@
 
       typedef typename ForwardMap::Value Value;
       typedef typename Parent::Edge Key;
-      
+
+      /// \brief Constructor      
+      ///
+      /// Constructor      
       CombinedEdgeMap() : forward_map(0), backward_map(0) {}
 
+      /// \brief Constructor      
+      ///
+      /// Constructor      
       CombinedEdgeMap(ForwardMap& _forward_map, BackwardMap& _backward_map) 
         : forward_map(&_forward_map), backward_map(&_backward_map) {}
       
+
+      /// \brief Sets the value associated with a key.
+      ///
+      /// Sets the value associated with a key.
       void set(const Key& e, const Value& a) { 
 	if (Parent::direction(e)) {
 	  forward_map->set(e, a); 
@@ -1317,6 +1372,9 @@
         } 
       }
 
+      /// \brief Returns the value associated with a key.
+      ///
+      /// Returns the value associated with a key.
       typename MapTraits<ForwardMap>::ConstReturnValue 
       operator[](const Key& e) const { 
 	if (Parent::direction(e)) {
@@ -1326,6 +1384,9 @@
         }
       }
 
+      /// \brief Returns the value associated with a key.
+      ///
+      /// Returns the value associated with a key.
       typename MapTraits<ForwardMap>::ReturnValue 
       operator[](const Key& e) { 
 	if (Parent::direction(e)) {
@@ -1335,10 +1396,16 @@
         }
       }
 
+      /// \brief Sets the forward map
+      ///
+      /// Sets the forward map
       void setForwardMap(ForwardMap& _forward_map) {
         forward_map = &_forward_map;
       }
 
+      /// \brief Sets the backward map
+      ///
+      /// Sets the backward map
       void setBackwardMap(BackwardMap& _backward_map) {
         backward_map = &_backward_map;
       }