lemon-0.x: comparison src/work/alpar/dijkstra.h

equal deleted inserted replaced

-:05ef95f9a6b5
+:07fe0c0e7d21
 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
 ///
 typedef typename Graph::template NodeMap<typename GR::Edge> PredMap;
 ///Instantiates a PredMap.
-///\todo Please document...
+///This function instantiates a \ref PredMap.
+///\param G is the graph, to which we would like to define the PredMap.
 ///\todo The graph alone may be insufficient for the initialization
 static PredMap *createPredMap(const GR &G)
 {
 return new PredMap(G);
 }
 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
 ///
 typedef typename Graph::template NodeMap<typename GR::Node> PredNodeMap;
 ///Instantiates a PredNodeMap.
-///\todo Please document...
+///This function instantiates a \ref PredNodeMap.
-///
+///\param G is the graph, to which we would like to define the \ref PredNodeMap
 static PredNodeMap *createPredNodeMap(const GR &G)
 {
 return new PredNodeMap(G);
 }
 ///\todo If it is set to a real map, Dijkstra::reached() should read this.
 ///\todo named parameter to set this type, function to read and write.
 typedef NullMap<typename Graph::Node,bool> ReachedMap;
 ///Instantiates a ReachedMap.
-///\todo Please document...
+///This function instantiates a \ref ReachedMap.
-///
+///\param G is the graph, to which we would like to define the \ref ReachedMap
 static ReachedMap *createReachedMap(const GR &G)
 {
 return new ReachedMap();
 }
 ///The type of the map that stores the dists of the nodes.
 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
 ///
 typedef typename Graph::template NodeMap<typename LM::Value> DistMap;
 ///Instantiates a DistMap.
-///\todo Please document...
+///This function instantiates a \ref DistMap.
-///
+///\param G is the graph, to which we would like to define the \ref DistMap
 static DistMap *createDistMap(const GR &G)
 {
 return new DistMap(G);
 }
 };
 ///
 bool reached(Node v) { return v==source || (*_pred)[v]!=INVALID; }
 };
+/// Default traits used by \ref DijkstraWizard
+/// To make it easier to use Dijkstra algorithm we created a wizard class.
+/// This \ref DijkstraWizard class also needs default traits.
+/// The \ref DijkstraWizardBase is a class to be the default traits of the
+/// \ref DijkstraWizard class.
 template<class GR,class LM>
 class DijkstraWizardBase : public DijkstraDefaultTraits<GR,LM>
 {
 typedef DijkstraDefaultTraits<GR,LM> Base;
 ///Pointer to the map of distances.
 void *_dist;
 ///Pointer to the source node.
 void *_source;
+/// Type of the nodes in the graph.
 typedef typename Base::Graph::Node Node;
 public:
+/// Constructor.
+/// This constructor does not require parameters, therefore it initiates
+/// all of the attributes to default values (0, INVALID).
 DijkstraWizardBase() : _g(0), _length(0), _pred(0), _predNode(0),
 		       _dist(0), _source(INVALID) {}
+/// Constructor.
+/// This constructor requires some parameters, listed in the parameters list.
+/// Others are initiated to 0.
+/// \param g is the initial value of  \ref _g
+/// \param l is the initial value of  \ref _length
+/// \param s is the initial value of  \ref _source
 DijkstraWizardBase(const GR &g,const LM &l, Node s=INVALID) :
 _g((void *)&g), _length((void *)&l), _pred(0), _predNode(0),
 		  _dist(0), _source((void *)&s) {}
 };
-///\e
+/// A class to make easier the usage of Dijkstra algorithm
-///\e
+/// This class is created to make it easier to use Dijkstra algorithm.
+/// It uses the functions and features of the plain \ref Dijkstra,
+/// but it is much more simple to use it.
 ///
+/// Simplicity means that the way to change the types defined
+/// in the traits class is based on functions that returns the new class
+/// and not on templatable built-in classes. When using the plain \Dijkstra
+/// the new class with the modified type comes from the original by using the ::
+/// operator. In this case only a function have to be called and it will
+/// return the needed class.
+///
+/// It does not have own \ref run method. When its \ref run method is called
+/// it initiates a plain \ref Dijkstra class, and calls the \ref Dijkstra::run
+/// method of it.
 template<class TR>
 class DijkstraWizard : public TR
 {
 typedef TR Base;
-//The type of the underlying graph.
+///The type of the underlying graph.
 typedef typename TR::Graph Graph;
 //\e
 typedef typename Graph::Node Node;
 //\e
 typedef typename Graph::NodeIt NodeIt;
 //\e
 typedef typename Graph::Edge Edge;
 //\e
 typedef typename Graph::OutEdgeIt OutEdgeIt;
-//The type of the map that stores the edge lengths.
+///The type of the map that stores the edge lengths.
 typedef typename TR::LengthMap LengthMap;
-//The type of the length of the edges.
+///The type of the length of the edges.
 typedef typename LengthMap::Value Value;
-//\brief The type of the map that stores the last
+///\brief The type of the map that stores the last
-//edges of the shortest paths.
+///edges of the shortest paths.
 typedef typename TR::PredMap PredMap;
-//\brief The type of the map that stores the last but one
+///\brief The type of the map that stores the last but one
-//nodes of the shortest paths.
+///nodes of the shortest paths.
 typedef typename TR::PredNodeMap PredNodeMap;
-//The type of the map that stores the dists of the nodes.
+///The type of the map that stores the dists of the nodes.
 typedef typename TR::DistMap DistMap;
-//The heap type used by the dijkstra algorithm.
+///The heap type used by the dijkstra algorithm.
 typedef typename TR::Heap Heap;
 public:
+/// Constructor.
 DijkstraWizard() : TR() {}
+/// Constructor that requires parameters.
+/// These parameters will be the default values for the traits class.
 DijkstraWizard(const Graph &g,const LengthMap &l, Node s=INVALID) :
 TR(g,l,s) {}
+///Copy constructor
 DijkstraWizard(const TR &b) : TR(b) {}
 ~DijkstraWizard() {}
-///\e
+///Runs Dijkstra algorithm from a given node.
+///Runs Dijkstra algorithm from a given node.
+///The node can be given by the \ref source function.
 void run()
 {
 if(_source==0) throw UninitializedData();
 Dijkstra<Graph,LengthMap,TR> Dij(*(Graph*)_g,*(LengthMap*)_length);
 if(_pred) Dij.predMap(*(PredMap*)_pred);
 if(_predNode) Dij.predNodeMap(*(PredNodeMap*)_predNode);
 if(_dist) Dij.distMap(*(DistMap*)_dist);
 Dij.run(*(Node*)_source);
 }
-///\e
+///Runs Dijkstra algorithm from a given node.
+///Runs Dijkstra algorithm from a given node.
+///\param s is the given source.
 void run(Node s)
 {
 _source=(void *)&s;
 run();
 }
 typedef T PredMap;
 static PredMap *createPredMap(const Graph &G) { return 0; };
 DefPredMapBase(const Base &b) : Base(b) {}
 };
-///\e
+/// \ref named-templ-param "Named parameter" function for setting PredMap type
+/// \ref named-templ-param "Named parameter" function for setting PredMap type
 template<class T>
 DijkstraWizard<DefPredMapBase<T> > predMap(const T &t)
 {
 _pred=(void *)&t;
 return DijkstraWizard<DefPredMapBase<T> >(*this);
 typedef T PredNodeMap;
 static PredNodeMap *createPredNodeMap(const Graph &G) { return 0; };
 DefPredNodeMapBase(const Base &b) : Base(b) {}
 };
-///\e
+/// \ref named-templ-param "Named parameter" function for setting PredNodeMap type
+/// \ref named-templ-param "Named parameter" function for setting PredNodeMap type
 template<class T>
 DijkstraWizard<DefPredNodeMapBase<T> > predNodeMap(const T &t)
 {
 _predNode=(void *)&t;
 return DijkstraWizard<DefPredNodeMapBase<T> >(*this);
 typedef T DistMap;
 static DistMap *createDistMap(const Graph &G) { return 0; };
 DefDistMapBase(const Base &b) : Base(b) {}
 };
-///\e
+/// \ref named-templ-param "Named parameter" function for setting DistMap type
+/// \ref named-templ-param "Named parameter" function for setting DistMap type
 template<class T>
 DijkstraWizard<DefDistMapBase<T> > distMap(const T &t)
 {
 _dist=(void *)&t;
 return DijkstraWizard<DefDistMapBase<T> >(*this);
 }
-///\e
+/// Sets the source node, from which the Dijkstra algorithm runs.
+/// Sets the source node, from which the Dijkstra algorithm runs.
+/// \param s is the source node.
 DijkstraWizard<TR> &source(Node s)
 {
 source=(void *)&s;
 return *this;
 }

changeset 1123	a2e93889a604
parent 1119	d3504fc075dc
child 1124	12623f7ecb37